elastic-agent-client.proto

// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
// or more contributor license agreements. Licensed under the Elastic License;
// you may not use this file except in compliance with the Elastic License.

syntax = "proto3";

package proto;

option cc_enable_arenas = true;
option go_package = "pkg/proto;proto";
import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

// Services that the client is allowed to use over the connection.
enum ConnInfoServices {
    // V1 checkin service.
    Checkin = 0;
    // V2 checkin service.
    CheckinV2 = 1;
    // Key-value store service.
    Store = 2;
    // Artifact store service.
    Artifact = 3;
    // Log service.
    Log = 4;
}

// Connection information sent to the application on startup so it knows how to connected back to the Elastic Agent.
//
// This is normally sent through stdin and should never be sent across a network un-encrypted.
message ConnInfo {
    // GRPC connection address.
    string addr = 1;
    // Server name to use when connecting over TLS.
    string server_name = 2;
    // Token that the application should send as the unique identifier when connecting over the GRPC.
    string token = 3;
    // CA certificate.
    bytes ca_cert = 4;
    // Peer certificate.
    bytes peer_cert = 5;
    // Peer private key.
    bytes peer_key = 6;
    // Allowed services that spawned process can use. (only used in V2)
    repeated ConnInfoServices services = 7;
}

// A status observed message is streamed from the application to Elastic Agent.
//
// This message contains the currently applied `config_state_idx` (0 in the case of initial start, 1 is the first
// applied config index) along with the status of the application. In the case that the sent `config_state_idx`
// doesn't match the expected `config_state_idx` that Elastic Agent expects, the application is always marked as
// `CONFIGURING`.
message StateObserved {
    // Status codes for the current state.
    enum Status {
        // Application is starting.
        STARTING = 0;
        // Application is currently configuring.
        CONFIGURING = 1;
        // Application is in healthy state.
        HEALTHY = 2;
        // Application is working but in a degraded state.
        DEGRADED = 3;
        // Application is failing completely.
        FAILED = 4;
        // Application is stopping.
        STOPPING = 5;
    }
    // Token that is used to uniquely identify the application to agent. When agent started this
    // application it would have provided it this token.
    string token = 1;
    // Current index of the applied configuration.
    uint64 config_state_idx = 2;
    // Status code.
    Status status = 3;
    // Message for the health status.
    string message = 4;
    // JSON encoded payload for the status.
    string payload = 5;
}

// A state expected message is streamed from the Elastic Agent to the application informing the application
// what Elastic Agent expects the applications state to be.
message StateExpected {
    enum State {
        // Expects that the application is running.
        RUNNING = 0;
        // Expects that the application is stopping.
        STOPPING = 1;
    }
    // Expected state of the application.
    State state = 1;
    // Index of the either current configuration or new configuration provided.
    uint64 config_state_idx = 2;
    // Resulting configuration. (If the application already has the current `config_state_idx` this
    // will be empty.)
    string config = 3;
}

// A action request is streamed from the Elastic Agent to the application so an action can be performed
// by the connected application.
message ActionRequest {
    // Type of action being performed.
    enum Type {
        // Custom action (registered by the unit)
        CUSTOM = 0;
        // Defined diagnostics action.
        DIAGNOSTICS = 1;
    }
    // Unique ID of the action.
    string id = 1;
    // Name of the action (name is ignored for DIAGNOSTICS).
    string name = 2;
    // JSON encoded parameters for the action.
    bytes params = 3;
    // Unique ID of the unit (only used with V2).
    string unit_id = 4;
    // Type of the unit (only used with V2).
    UnitType unit_type = 5;
    // Type of action to be performed (only used with V2).
    Type type = 6;
}

message ActionDiagnosticUnitResult {
    // Human readable name of the diagnostic result content.
    string name = 1;
    // Filename to use to store the diagnostic to the disk.
    string filename = 2;
    // Human readable description of the information this diagnostic provides.
    string description = 3;
    // Content-Type of the resulting content.
    string content_type = 4;
    // Actual file content.
    bytes content = 5;
    // Timestamp the content was generated at.
    google.protobuf.Timestamp generated = 6;
}

// An action response is streamed from the application back to the Elastic Agent to provide a result to
// an action request.
message ActionResponse {
    // Status result of the action.
    enum Status {
        // Action was successful.
        SUCCESS = 0;
        // Action has failed.
        FAILED = 1;
    }
    // Token that is used to uniquely identify the application to agent. When agent started this
    // application it would have provided it this token.
    string token = 1;
    // Unique ID of the action.
    string id = 2;
    // Status of the action.
    Status status = 3;
    // JSON encoded result for the action (empty when diagnostic action response).
    bytes result = 4;
    // Specific result for diagnostics action. (only used in V2)
    repeated ActionDiagnosticUnitResult diagnostic = 5;
}

// State codes for the current state.
enum State {
    // STARTING is an optional observed state indicating the unit is doing work to start before
    // transitioning to HEALTHY.
    STARTING = 0;
    // CONFIGURING is an optional observed state indicating the unit is started and being configured
    // prior to transitioning to HEALTHY. Typically reported when a units current configuration does
    // not match its expected configuration.
    CONFIGURING = 1;
    // HEALTHY is a required observed and expected state. The agent sends an expected state of
    // HEALTHY when a unit should be started and running.
    HEALTHY = 2;
    // DEGRADED is an optional observed state indicating the unit experienced a non-fatal error.
    DEGRADED = 3;
    // FAILED is an optional observed state indicating the unit experienced a fatal error.
    FAILED = 4;
    // STOPPING is an optional observed state indicating the unit is doing the work required to STOP
    // before transitioning to STOPPED.
    STOPPING = 5;
    // STOPPED is a required observed and expected state. The agent sends an expected state of
    // STOPPED when a unit should stop running.
    STOPPED = 6;
}

// Type of unit.
enum UnitType {
    INPUT = 0;
    OUTPUT = 1;
}

// Log level for the unit.
enum UnitLogLevel {
    ERROR = 0;
    WARN = 1;
    INFO = 2;
    DEBUG = 3;
    TRACE = 4;
}

// Package metadata provided in the meta field of a unit.
message Package {
    // Source is the original source of the message. All values from the message are included here
    // even if other concrete fields are defined for this message.
    google.protobuf.Struct source = 1;
    // Name of the package.
    string name = 2;
    // Version of the package.
    string version = 3;
}

// Metadata provided in the meta field of a unit.
message Meta {
    // Source is the original source of the message. All values from the message are included here
    // even if other concrete fields are defined for this message.
    google.protobuf.Struct source = 1;
    // Package metadata.
    Package package = 2;
}

// Data stream defined in either top-level unit or in multiple streams in the unit.
message DataStream {
    // Source is the original source of the message. All values from the message are included here
    // even if other concrete fields are defined for this message.
    google.protobuf.Struct source = 1;
    // Dataset for the stream.
    string dataset = 2;
    // Type for the stream.
    string type = 3;
    // Namespace for the stream.
    string namespace = 4;
}

// Stream defined in a configuration.
message Stream {
    // Source is the original source of the message. All values from the message are included here
    // even if other concrete fields are defined for this message.
    google.protobuf.Struct source = 1;
    string id = 2;
    DataStream data_stream = 3;
}

// A units expected configuration.
message UnitExpectedConfig {
    // Source is the original source of the message. All values from the configuration are included here
    // even if other concrete fields are defined for this message.
    google.protobuf.Struct source = 1;
    // Unique ID for the Unit.
    string id = 2;
    // Type of the unit.
    string type = 3;
    // Name of the unit.
    string name = 4;
    // Revision of the unit.
    uint64 revision = 5;
    // Metadata information of the unit.
    Meta meta = 6;
    // Unit-level data stream.
    DataStream data_stream = 7;
    // Multiple streams per unit.
    repeated Stream streams = 8;
}

// A unit that is part of a collector/shipper.
message UnitExpected {
    // Unique ID of the unit.
    string id = 1;
    // Unit type.
    UnitType type = 2;
    // Expected state of the unit. Will always be one of HEALTHY or STOPPED.
    State state = 3;
    // Index of the either current configuration or new configuration provided.
    uint64 config_state_idx = 4;
    // Resulting configuration. (If the application already has the current `config_state_idx` this
    // will be empty.)
    UnitExpectedConfig config = 5;
    // Log level of the unit.
    UnitLogLevel log_level = 6;
}

// Only provided on first checkin expected response to the component.
//
// Includes the agent information that the component might want to use for its events.
message CheckinAgentInfo {
    // ID is the Elastic Agent's unique ID.
    string id = 1;
    // Version is the version of the running Elastic Agent.
    string version = 2;
    // Snapshot is true when the running Elastic Agent is a snapshot version.
    bool snapshot = 3;
}

// Feature flags configurations.
message Features {
    // Source is the original source of the features. All values from the features
    // are included here even if other concrete fields are defined for this message.
    google.protobuf.Struct source = 1;

    FQDNFeature fqdn = 2;
}

// FQDN feature flag indicates to use FQDN for host.name instead of hostname.
message FQDNFeature {
    bool enabled = 1;
}

// A set of units and their expected states and configuration.
message CheckinExpected {
    // Units is the expected units the component should be running.
    repeated UnitExpected units = 1;
    // Agent info is provided only on first CheckinExpected response to the component.
    CheckinAgentInfo agent_info = 2;

    // Features are the expected feature flags configurations.
    // Added on Elastic Agent v8.7.1.
    Features features = 3;
    // Index of the either current features configuration or new the configuration provided.
    uint64 features_idx = 4;
}

// Observed status for a unit.
//
// Contains the currently applied `config_state_idx` (0 in the case of initial start, 1 is the first
// applied config index) along with the status of the application. In the case that the sent `config_state_idx`
// doesn't match the expected `config_state_idx` that Elastic Agent expects, the unit is always marked as
// `CONFIGURING` and a new `UnitExpected` will be sent to so it can have the latest configuration.
message UnitObserved {
    // Unique ID of the unit.
    string id = 1;
    // Unit type.
    UnitType type = 2;
    // Current index of the applied configuration.
    uint64 config_state_idx = 3;
    // Current state of the unit.
    State state = 4;
    // Human readable message for the state of the unit.
    // Exposed to users to provide more detail about the state for this single unit.
    string message = 5;
    // Payload for the current state.
    google.protobuf.Struct payload = 6;
}

// Observed version information for the running program.
message CheckinObservedVersionInfo {
    // Name of the binary.
    string name = 1;
    // Version of the binary.
    string version = 2;
    // Additional metadata about the binary.
    map<string, string> meta = 3;
}

// Observed statuses and configuration for defined units.
//
// In the case that a unit is missing from the observation then the Elastic Agent will mark that missing unit
// as `STARTING` and send a new `UnitExpected` for the missing unit.
message CheckinObserved {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Units observed state.
    repeated UnitObserved units = 2;
    // Version information about the running program. Should always be included on first checkin, and not again unless
    // one of the values have changed.
    optional CheckinObservedVersionInfo version_info = 3;

    // Features are the expected feature flags configurations.
    // Added on Elastic Agent v8.7.1.
    Features features = 4;
    // Index of the either current features configuration or new the configuration provided.
    uint64 features_idx = 5;
}

service ElasticAgent {
    // Called by the client to provide the Elastic Agent the state of the application.
    //
    // A `StateObserved` must be streamed at least every 30 seconds or it will result in the
    // application be automatically marked as FAILED, and after 60 seconds the Elastic Agent will
    // force kill the entire process and restart it.
    rpc Checkin(stream StateObserved) returns (stream StateExpected);

    // Called by the client to provide the Elastic Agent the state of the application over the V2 protocol.
    //
    // A `CheckinObserved` must be streamed at least every 30 seconds or it will result in the
    // set of units automatically marked as FAILED, and after 60 seconds the Elastic Agent will
    // force kill the entire process and restart it.
    rpc CheckinV2(stream CheckinObserved) returns (stream CheckinExpected);

    // Called by the client on connection to the GRPC allowing the Elastic Agent to stream action
    // requests to the application and the application stream back responses to those requests.
    //
    // Request and response is swapped here because the Elastic Agent sends the requests in a stream
    // to the connected process. The order of response from the process does not matter, it is acceptable
    // for the response order to be different then the request order.
    rpc Actions(stream ActionResponse) returns (stream ActionRequest);
}

// Type of transaction to start.
enum StoreTxType {
    READ_ONLY = 0;
    READ_WRITE = 1;
}

// Begins a new transaction.
//
// A started transaction must either have commit or discard called.
message StoreBeginTxRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // ID of the unit.
    string unit_id = 2;
    // Type of the unit.
    UnitType unit_type = 3;
    // Type of transaction to start.
    StoreTxType type = 4;
}

// Response for a started transaction.
message StoreBeginTxResponse {
    // Transaction ID.
    string id = 1;
}

// Gets a key from the store.
message StoreGetKeyRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Transaction ID.
    string tx_id = 2;
    // Name of the key.
    string name = 3;
}

// Response of the retrieved key.
message StoreGetKeyResponse {
    // Status result of the get.
    enum Status {
        // Action was successful.
        FOUND = 0;
        // Action has failed.
        NOT_FOUND = 1;
    }
    Status status = 1;
    // Value when `FOUND`.
    bytes value = 2;
}

// Sets a key into the store.
//
// `tx_id` must be an ID of a transaction that was started with `READ_WRITE`.
message StoreSetKeyRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Transaction ID.
    string tx_id = 2;
    // Name of the key.
    string name = 3;
    // Value of the key.
    bytes value = 4;
    // TTL of the key (in milliseconds)
    uint64 ttl = 5;
}

// Response from `SetKey`.
message StoreSetKeyResponse {
    // Empty at the moment, defined for possibility of adding future return values.
}

// Deletes a key in the store.
//
// `tx_id` must be an ID of a transaction that was started with `READ_WRITE`.
//
// Does not error in the case that a key does not exist.
message StoreDeleteKeyRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Transaction ID.
    string tx_id = 2;
    // Name of the key.
    string name = 3;
}

// Response from `DeleteKey`.
message StoreDeleteKeyResponse {
    // Empty at the moment, defined for possibility of adding future return values.
}

// Commits the transaction in the store.
//
// Upon error the whole transaction is discarded so no need to call discard after error.
message StoreCommitTxRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Transaction ID.
    string tx_id = 2;
}

// Response from `CommitTx`.
message StoreCommitTxResponse {
    // Empty at the moment, defined for possibility of adding future return values.
}

// Discards the transaction in the store.
message StoreDiscardTxRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Transaction ID.
    string tx_id = 2;
}

// Response from `DiscardTx`.
message StoreDiscardTxResponse {
    // Empty at the moment, defined for possibility of adding future return values.
}

service ElasticAgentStore {
    // Key-Value state storage is provided for each unit.
    //
    // Transactional store is provided to allow multiple key operations to occur before a commit to ensure consistent
    // state when multiple keys make up the state of an units persistent state.
    rpc BeginTx(StoreBeginTxRequest) returns (StoreBeginTxResponse);
    rpc GetKey(StoreGetKeyRequest) returns (StoreGetKeyResponse);
    rpc SetKey(StoreSetKeyRequest) returns (StoreSetKeyResponse);
    rpc DeleteKey(StoreDeleteKeyRequest) returns (StoreDeleteKeyResponse);
    rpc CommitTx(StoreCommitTxRequest) returns (StoreCommitTxResponse);
    rpc DiscardTx(StoreDiscardTxRequest) returns (StoreDiscardTxResponse);
}

// Requests an artifact from the Elastic Agent.
message ArtifactFetchRequest {
    // Token that is used to uniquely identify the collection of inputs to the agent. When started this is provided
    // in the `ConnInfo`.
    string token = 1;
    // ID of the artifact.
    string id = 2;
    // SHA256 of the artifact.
    string sha256 = 3;
}

// Content of the artifact.
message ArtifactFetchResponse {
    oneof content_eof {
        // Artifact content.
        bytes content = 1;
        // End-of-file.
        google.protobuf.Empty eof = 2;
    }
}

service ElasticAgentArtifact {
    // Fetches an artifact from the artifact store.
    //
    // Response from this call can be chunked over multiple `ArtifactFetchResponse` for very large responses. A minimum
    // of two responses will always be returned. The last response has eof set.
    rpc Fetch(ArtifactFetchRequest) returns (stream ArtifactFetchResponse);
}

message LogMessage {
    // ID of the unit.
    string unit_id = 1;
    // Type of the unit.
    UnitType unit_type = 2;
    // ECS log message body JSON encoded.
    bytes message = 3;
}

message LogMessageRequest {
    // Token that is used to uniquely identify the connection to the Elastic Agent.
    string token = 1;
    // Multiple message to report at the same time.
    repeated LogMessage messages = 2;
}

message LogMessageResponse {
    // Empty at the moment, defined for possibility of adding future return values.
}

// Log service is only exposed to programs that are not started as sub-processes by Elastic Agent.
//
// This allows services that are not started as sub-processes to write to the same stdout that programs that are
// started as subprocess. A program that is as a sub-process with stdout connected does not have the ability to use
// this service.
service ElasticAgentLog {
    // Log messages to the Elastic Agent.
    rpc Log(LogMessageRequest) returns (LogMessageResponse);
}