estransport

Documentation

Overview

Package estransport decodes Elasticsearch internal transport protocol frames. The transport protocol runs on TCP/9300 and is used for inter-node communication within an Elasticsearch cluster — NOT the HTTP REST API on TCP/9200.

Elasticsearch transport protocol is the binary protocol that cluster nodes use to exchange cluster state, shard assignments, search results, and index operations. It is distinct from the HTTP REST API (TCP/9200) that clients use.

The transport protocol (ES 7.x+) uses the following framing:

• total_size (4 BE): total message size including all following bytes
• "ES" marker (2 bytes): 0x45 0x53 — magic prefix
• header_size (VInt encoded): size of the variable header
• request_id (8 BE): long — monotonically increasing per connection
• status (1 byte): bit flags bit 0 (0x01) — request bit 1 (0x02) — response bit 2 (0x04) — error bit 3 (0x08) — compressed bit 4 (0x10) — handshake
• version (VInt encoded): transport protocol version (internal versioning)
• action name (length-prefixed string): operation identifier

Action names reveal the internal operation being performed. Examples:

"internal:cluster/state"     — cluster state sync
"internal:cluster/nodes"     — node discovery
"indices:data/read/search"   — search request
"indices:data/write/index"   — document indexing
"indices:admin/create"       — index creation
"cluster:monitor/nodes/info" — node info query

Security relevance:

• ES transport (TCP/9300) has NO authentication in default configs
• Any node speaking the transport protocol can join the cluster
• Transport traffic contains index data, search queries, cluster state
• Action names reveal internal operations and API surface
• NOT the same as the REST API (TCP/9200)
• Misconfigured ES clusters frequently exposed to internet on TCP/9300
• Joining an ES cluster gives full read/write access to all indices

Wrap-vs-native judgement

Native. The Elasticsearch transport framing is a deterministic
binary format with a fixed "ES" magic marker, BE integers, VInt
encoded fields, and length-prefixed strings. No crypto at the
parse layer.

What this package covers

• "ES" (0x45 0x53) magic marker detection
• total_size (4 BE) frame size
• request_id (8 BE) long
• status byte flags: compressed, handshake, error, request, response
• transport_version (VInt)
• action_name string extraction (length-prefixed)
• Classification: is_cluster_state, is_search, is_index, is_handshake, is_internal_action

What this package does NOT cover (deliberately out of scope)

• ES 6.x and earlier transport framing variants
• Message body / response payload parsing
• TLS transport layer (ES 8.x xpack.security.transport.ssl)
• Cluster join protocol beyond handshake detection
• Credential extraction (ES transport does not carry credentials in the frame header in default config)

Index

• type Result
  • func Decode(hexStr string) (*Result, error)

Types

type Result

type Result struct {
	TotalBytes int `json:"total_bytes"`

	HasESMarker      bool   `json:"has_es_marker"`
	MessageSize      int    `json:"message_size,omitempty"`
	RequestID        int64  `json:"request_id,omitempty"`
	TransportVersion int    `json:"transport_version,omitempty"`
	ActionName       string `json:"action_name,omitempty"`

	// Status flags decoded from the status byte
	StatusFlags  int  `json:"status_flags,omitempty"`
	IsRequest    bool `json:"is_request"`
	IsResponse   bool `json:"is_response"`
	IsError      bool `json:"is_error"`
	IsCompressed bool `json:"is_compressed"`
	IsHandshake  bool `json:"is_handshake"`

	// Action classification
	IsClusterState   bool `json:"is_cluster_state"`
	IsSearch         bool `json:"is_search"`
	IsIndex          bool `json:"is_index"`
	IsHandshakeFrame bool `json:"is_handshake_frame"`
	IsInternalAction bool `json:"is_internal_action"`
}

Result is the structured decode of an Elasticsearch transport frame.

func Decode

func Decode(hexStr string) (*Result, error)

Decode parses an Elasticsearch transport protocol frame from a hex string.