Protocol Reference

Proto Packages

Control Service (gRPC)

service ControlService {
    // Enrollment - called once to register agent
    rpc Enroll(EnrollRequest) returns (EnrollResponse);
    
    // Certificate renewal - called before cert expires
    rpc RenewCertificate(RenewCertificateRequest) returns (RenewCertificateResponse);
    
    // Bidirectional command stream - main communication channel
    rpc CommandStream(stream CommandResponse) returns (stream Command);
}

Key Messages

EnrollRequest

message EnrollRequest {
    string enrollment_token = 1;
    bytes csr = 2;                    // PEM-encoded CSR
    string machine_fingerprint = 3;
    string agent_version = 4;
    string hostname = 5;
    OSType os_type = 6;
    string os_version = 7;
    Architecture arch = 8;
}

Command

message Command {
    string command_id = 1;
    Timestamp issued_at = 2;
    int32 timeout_seconds = 3;
    
    oneof command {
        ConfigPush config_push = 10;
        ShellExecCommand shell_exec = 11;
        ServiceControlCommand service_control = 12;
        FileOperation file_operation = 13;
        SystemControlCommand system_control = 14;
        // ... more command types
    }
}

Heartbeat

message Heartbeat {
    string agent_id = 1;
    Timestamp timestamp = 2;
    uint64 config_version = 3;
    OperationalState operational_state = 4;
    SystemStatus system_status = 5;
}

Info Batch (QUIC)

message InfoBatch {
    string agent_id = 1;
    string agent_version = 2;
    string info_version = 3;
    uint64 batch_id = 4;
    Timestamp collected_at = 5;
    
    // Payload - one or more per batch
    repeated MetricSample metrics = 10;
    repeated LogEntry logs = 11;
    repeated NetworkConnection connections = 12;
    repeated ConnectionEvent connection_events = 13;
    Inventory inventory = 14;
    repeated SecurityEvent security_events = 15;
}

Versioning Rules