greet

Greet is a lightweight Go library to test greet / ping / handshake process in TCP, UDP and other popular protocols based on them.

Goals

• Fast: The library only performs handshake without entering full session
• Secure: The process ends before authentication / authorization step
• Lightweight: The library constructs raw command from scratch and does not depend on third-party service clients
• Tracing: The library outputs helpful errors from connection init to handshake

Use case

• Greet is good enough to test connectivity, service name and service version.

Installation

Library

go get github.com/crystade/greet@latest

Then import and use in your Go code:

import "github.com/crystade/greet"

func main() {
    ctx := context.Background()
    result, err := greet.Greet(ctx, "ssh", "github.com:22")
    // ...
}

CLI

go install github.com/crystade/greet/cmd/greet@latest

Or build from source:

go build -o greet ./cmd/greet/

Library Usage

The greet.Greet() function is the primary entry point:

result, err := greet.Greet(ctx, "ssh", "github.com:22")
if err != nil {
    // handle *greet.GreetError
}
fmt.Println(result.Success, result.TTDR, result.RTT, result.TTFB, result.TTLB, result.Data)

Customize behavior with functional options:

result, err := greet.Greet(ctx, "minecraft", "hypixel.net:25565",
    greet.WithTimeout(10*time.Second),
    greet.WithProtocolConfig(&minecraft.Config{ProtocolVersion: 775}),
)

For pre-resolved protocols, use greet.GreetWith():

p, _ := greet.Get("ssh")
result, err := greet.GreetWith(ctx, p, "github.com", 22)

See greet.go and options.go for the complete API.

CLI Usage

greet <protocol> <host>[:<port>] [flags]

Commands

Examples

# Generic TCP — test connectivity to a port
greet tcp example.com:80

# SSH — read server version banner
greet ssh github.com:22

# PostgreSQL — probe SSL support
greet postgresql localhost:5432

# PostgreSQL — skip SSL probe
greet postgresql localhost:5432 --sslmode=disable

# Minecraft Java — query server status
greet minecraft hypixel.net:25565

# Minecraft — specify protocol version (default: 775)
greet minecraft localhost:25565 --protocol-version=775

# Use default port (from protocol's well-known port)
greet ssh github.com        # equivalent to github.com:22

# TLS — check leaf certificate
greet tls expired.badssl.com:443

Output

All commands output structured results to stdout with timing metrics. All four timing metrics share the same starting anchor time:

|------|         TTDR: from start to when DNS resolves
|------|--|      RTT:  from start to when first ACK at TCP transport or Receive at UDP
|------|--|-|    TTFB: from start to when first byte response at the correct protocol layer
|------|--|-------| TTLB: from start to when last byte response at the correct protocol layer

Example CLI output:

Protocol: ssh
Transport: tcp
TTDR: 12.345ms
RTT: 34.567ms
TTFB: 45.123ms
TTLB: 45.200ms
Success: true
Version String: SSH-2.0-OpenSSH_8.9

Errors are output as JSON to stderr:

{
  "success": false,
  "error": "[ssh] connection_refused: connection to localhost:22 refused",
  "code": "connection_refused",
  "protocol": "ssh"
}

Protocol-Specific Flags

Protocols

Error Code Reuse Hierarchy

Protocols inherit error codes from their transport layer:

graph TD
    COMMON[Common Errors]
    TCP[Generic TCP Errors]
    UDP[Generic UDP Errors]
    SSH[SSH Errors]
    PG[PostgreSQL Errors]
    MC[Minecraft Errors]
    TLS[TLS Errors]

    COMMON --> TCP
    COMMON --> UDP
    TCP --> SSH
    TCP --> PG
    TCP --> MC
    TCP --> TLS

Common Errors

Generic TCP Errors

Generic UDP Errors

Generic TCP

• Input: Host, Port
• Output: Success with TTDR/RTT/TTFB/TTLB timing, or an error code from Common + Generic TCP errors

Generic UDP

• Input: Host, Port
• Output: Success with TTDR/RTT/TTFB/TTLB timing, or an error code from Common + Generic UDP errors

SSH (TCP)

• Input: Host, Port (default 22)
• Output: Success with server version string (e.g. SSH-2.0-OpenSSH_8.9) and TTDR/RTT/TTFB/TTLB timing, or an error code

Inherits: Common + Generic TCP errors

PostgreSQL (TCP)

• Input: Host, Port (default 5432), SSL Mode (default prefer)
• Output: Success with SSL support flag and TTDR/RTT/TTFB/TTLB timing, or an error code

Inherits: Common + Generic TCP errors

Minecraft Java (TCP)

• Input: Host, Port (default 25565), Protocol Version (required, VarInt — e.g. 775 for Minecraft 26.1). Intent is automatically set to Status (1) by the library.
• Output: Success with server status JSON (MOTD, players, version) and TTDR/RTT/TTFB/TTLB timing, or an error code

Inherits: Common + Generic TCP errors

TLS (TCP)

• Input: Host, Port (default 443)
• Output: Success with leaf certificate details, presented certificate chain, and TTDR/RTT/TTFB/TTLB timing, or an error code

Inherits: Common + Generic TCP errors

Limitation: This is a lightweight certificate metadata probe, not a full browser/WebPKI validator. It does not perform trust-chain verification, revocation queries (OCSP/CRL fetching), SCT/CT policy checks, EKU validation, or name-constraint enforcement. The checks are heuristic and inspired by Chrome's CERT_* flags, but are not equivalent to Chrome's security UI.

Certificate Status (status field)

The status field is the chain-level status: it holds the CERT_* flags from the first certificate (walking leaf → root) that has a non-OK check, or ["OK"] if every certificate in the chain passes all checks. Multiple flags can appear simultaneously.

Each certificate in the cert_chain array also carries its own per-certificate status. The checks that apply depend on the certificate's role:

• Leaf-only checks: CERT_COMMON_NAME_INVALID, CERT_AUTHORITY_INVALID(self-signed), CERT_SELF_SIGNED_LOCAL_NETWORK, CERT_VALIDITY_TOO_LONG
• All certs: CERT_DATE_INVALID, CERT_WEAK_SIGNATURE_ALGORITHM, CERT_WEAK_KEY
• Non-self-signed certs: CERT_NO_REVOCATION_MECHANISM (root CAs are self-signed and excluded)

Contribution

Due to overhead of maintenance, we only accept popular protocols for now.

Postpone:

• DNS: having the most RFCs and Drafts attached to it of all protocols, we are looking to provide support to a subset of popular DNS protocols only

License

This project is licensed under the MIT License - see the LICENSE file for details.