A lightweight, lightning-fast, and feature-complete Go wrapper for the Check-Host.cc API. Full API reference: check-host.cc/docs. A bundled OpenAPI 3.0.3 / Swagger spec ships at swagger.yaml for codegen / offline browsing.
Seamlessly integrate global network diagnostics into your backend. Perform remote Ping, MTR, DNS, HTTP, TCP and UDP checks from multiple worldwide locations—straight from your Go application. Checks from 60+ locations worldwide.
- Zero Dependencies: Built purely on the native Go
net/httpstandard library. Zero package bloat. - Bulletproof Payloads: Strictly utilizes POST requests for all active monitoring endpoints. This completely eliminates nasty URL-encoding issues with complex hostnames or custom UDP payloads.
- Modern & Clean: Written idiomatically with clear configuration structures and typed responses.
- Header-Based Authentication: Configure your token once during client initialization; the SDK attaches it as an
Authorization: Bearerheader to every request. The token never lands in a URL or a request body. - Network Intelligence & Fullscan: Passive IP / ASN / prefix / domain / certificate / port / software lookups, plus deep on-demand scans with a built-in polling helper.
- Go: 1.18+
Install the package directly using go get:
go get github.com/Check-Host/go-libpackage main
import (
"fmt"
"log"
checkhost "github.com/Check-Host/go-lib"
)
func main() {
// Initialize the client. The API token is optional.
// Without a token, standard public rate limits apply.
// client := checkhost.NewClient("YOUR_API_TOKEN_UUID")
client := checkhost.NewClient("")
// Example: Retrieve all current nodes
locations, err := client.Locations()
if err != nil {
log.Fatalf("Error: %v", err)
}
fmt.Printf("Successfully retrieved %d global nodes.\n", len(locations))
}The token is sent as an Authorization: Bearer <token> header on every
request — GET, POST and binary alike. It is never placed in the query string
or the request body, so it does not leak into access logs, referrer headers
or browser history.
client := checkhost.NewClient("YOUR_API_TOKEN_UUID")
// Or set it on an existing client
client.Token = "YOUR_API_TOKEN_UUID"Migrating from v1.0: the token used to travel in the JSON body as an
apikeyfield. That field is deprecated server-side.NewClientis positional and unchanged, socheckhost.NewClient(yourToken)keeps working as-is. TheCheckHost.APIKeystruct field still authenticates but is deprecated in favour ofCheckHost.Token, which takes precedence when both are set.
This library supports both minimal invocations and detailed, options-rich requests for every endpoint. All failures (network issues, API errors, rate limits) return standard error types encapsulating the actual check-host API response message.
Many endpoints accept a specific Request struct containing optional configuration fields:
Region: Array of Nodes or ISO Country Codes (e.g.[]string{"DE", "NL"}) or Continents (e.g.[]string{"EU"}).RepeatChecks: Number of repeated probes to perform per node for higher accuracy (Live Check).Timeout: Per-check timeout in milliseconds (100–30000). Optional; each check type has its own default (ping/tcp 1000, udp 2000, dns 5000, http 15000, mtr 1000). A value below 100 is read as seconds and converted, so older code that passedtimeout: 15still works — but new code should pass milliseconds.
Note: In Go, passing nil as the configuration object will automatically invoke the minimum configuration defaults required by the Check-Host API.
Returns the requesting client's public IPv4 or IPv6 address.
ip, err := client.MyIP()Fetches a dynamic list of all currently active monitoring nodes across the globe.
nodes, err := client.Locations()Retrieves detailed geolocation data, ISP information, and ASN details.
// Minimal Example
info, err := client.Info("check-host.cc")Performs a WHOIS registry lookup.
// Minimal Example
whois, err := client.Whois("check-host.cc")Monitoring endpoints initiate tasks asynchronously and return a CheckCreated object containing an UUID. Use the Report() method (documented below) to fetch the actual results.
Dispatches ICMP echo requests to the target from global nodes.
// Minimal Example
pingMin, err := client.Ping("8.8.8.8", nil)
// Max Example (With options)
pingMax, err := client.Ping("8.8.8.8", &checkhost.MonitoringRequest{
Region: []string{"DE", "NL"},
RepeatChecks: 5,
Timeout: 5,
})Queries global nameservers for specific DNS records.
// Minimal Example
dnsMin, err := client.DNS("check-host.cc", nil)
// Max Example (With options - TXT Record)
dnsMax, err := client.DNS("check-host.cc", &checkhost.DNSTargetRequest{
QueryMethod: "TXT", // A, AAAA, MX, TXT, SRV, etc.
Region: []string{"US", "DE"},
})Attempts to establish a 3-way TCP handshake on a specific destination port.
// Minimal Example (Target, Port)
tcpMin, err := client.TCP("1.1.1.1", 443, nil)
// Max Example (With options)
tcpMax, err := client.TCP("1.1.1.1", 80, &checkhost.TCPMonitoringRequest{
MonitoringRequest: checkhost.MonitoringRequest{
Region: []string{"DE", "NL"},
RepeatChecks: 3,
Timeout: 10,
},
})Sends UDP packets to a specified target and port.
// Minimal Example (Target, Port)
udpMin, err := client.UDP("1.1.1.1", 53, nil)
// Max Example (With custom hex payload and options)
udpMax, err := client.UDP("1.1.1.1", 123, &checkhost.UDPMonitoringRequest{
Payload: "0b", // NTP Request Hex
MonitoringRequest: checkhost.MonitoringRequest{
Region: []string{"EU"},
RepeatChecks: 2,
Timeout: 5,
},
})Executes an HTTP/HTTPS request to the target to measure TTFB and latency.
// Minimal Example
httpMin, err := client.Http("https://check-host.cc", nil)
// Max Example (With options)
httpMax, err := client.Http("https://check-host.cc", &checkhost.MonitoringRequest{
Region: []string{"US", "DE"},
RepeatChecks: 3,
Timeout: 10,
})Initiates an MTR (My Traceroute) diagnostic.
// Minimal Example
mtrMin, err := client.MTR("1.1.1.1", nil)
// Max Example (With protocols, IP forced, and options)
mtrMax, err := client.MTR("1.1.1.1", &checkhost.MTRMonitoringRequest{
RepeatChecks: 15,
ForceIPVersion: 4, // 4 or 6
ForceProtocol: "TCP", // default is ICMP
Region: []string{"DE", "US"},
})Fetches the compiled report and real-time statuses from a previously initiated monitoring check (Ping, TCP, HTTP, etc.) using its unique UUID. Wait 1-2 seconds after starting a check before polling. Longer checks with multiple repeats take one check per second and can be requested multiple times.
// The check UUID is returned by any monitoring method above
taskUuid := "c0b4b0e3-aed7-4ae2-9f53-7bac879697cb"
// Fetch the result payload
report, err := client.Report(taskUuid)Passive lookups against the dataset behind the entity pages — no check is dispatched to the monitoring nodes, so results come back immediately. Each response has a typed envelope plus a Data map (IntelData), which stays untyped because the key set differs per endpoint and sections we hold no data for come back empty or null.
Reverse DNS, open ports and banners, TLS certificates, BGP/ASN attribution, GeoIP, tech-stack, co-hosted domains, origin-leak candidates, threat-intel matches and honeypot activity.
intel, err := client.IPIntel("1.1.1.1")
if bgp, ok := intel.Data["bgp"].(map[string]interface{}); ok {
fmt.Println(bgp["as_name"], bgp["rpki_status"])
}Honeypot passwords are never returned in cleartext — entries expose only password_captured (bool) and password_len.
Prefix counts, announced IP totals, peers / providers / customers, IXP memberships, RPKI coverage, GeoIP footprint and hosted-domain summaries. Accepts "13335" or "AS13335".
intel, err := client.ASNIntel("AS13335")
fmt.Println(intel.ASN, intel.ASName, intel.Data["prefix_count"])prefix, err := client.PrefixIntel("1.1.1.0", 24)
domain, err := client.DomainIntel("check-host.cc")
cert, err := client.CertIntel("3a1b8f0c…9f90") // 64-char hex fingerprint
fmt.Println(prefix.CIDR, prefix.AnycastLabel)
fmt.Println(domain.Data["subdomains"])
fmt.Println(cert.Data["served_by"])port, err := client.PortIntel(443)
fmt.Println(port.WellKnown, port.Data["open_ips"])
nginx, err := client.SoftwareIntel("nginx", "") // all versions
pinned, err := client.SoftwareIntel("nginx", "1.24.0") // one versionA deep, on-demand multi-stage scan (ports + banners + TLS + DNS + threat-intel) of an IP, CIDR, domain or ASN. Asynchronous: submit, poll, then read the results. Budget minutes, not seconds.
job, err := client.Fullscan("check-host.cc", checkhost.ScopeDeep)
if err != nil {
log.Fatal(err)
}
fmt.Println(job.UUID, job.Status) // ... pending
// Block until the job reaches a terminal status (complete/partial/failed).
// On timeout you get the last observed job alongside the error.
finished, err := client.WaitForFullscan(job.UUID, 5*time.Second, 5*time.Minute)
fmt.Printf("%s %.0f%%\n", finished.Status, finished.Progress()*100)
results, err := client.FullscanResults(job.UUID)
for _, entry := range results.Data.OpenPorts {
fmt.Println(entry["port"], entry["service"])
}Scopes: checkhost.ScopeBasic (top-100 ports + banner), checkhost.ScopeDeep (default — full port range, TLS, body and threat-intel), checkhost.ScopeFull (deep plus subdomain enumeration; domains only). Passing "" selects ScopeDeep.
Anonymous CIDR submissions are capped at /24 (v4) and /120 (v6); an API token raises that to /20 and /112.
Before dispatching a scan, check whether a recent one already exists:
scans, err := client.RecentScans("check-host.cc")
for _, prior := range scans.RecentScans {
if prior.IsFinished() {
results, err := client.FullscanResults(prior.UUID)
break
}
}FullscanJob exposes IsFinished() (terminal status) and Progress() (SubjobsDone / SubjobsTotal, clamped to [0, 1]).
| Method | Endpoint |
|---|---|
MyIP() |
GET /myip |
MyInfo() |
GET /myinfo |
Locations() |
GET /locations |
Info(target) |
POST /info |
Whois(target) |
POST /whois |
Ping(target, opts) |
POST /ping |
DNS(target, opts) |
POST /dns |
TCP(target, port, opts) |
POST /tcp |
UDP(target, port, opts) |
POST /udp |
Http(target, opts) |
POST /http |
MTR(target, opts) |
POST /mtr |
Report(uuid) |
GET /report/{uuid} |
OgImage(uuid) |
GET /report/{uuid}/og-image |
CountryMap(uuid, format, res) |
GET /report/{uuid}/country-map |
IPIntel(ip) |
GET /ip/{ip} |
ASNIntel(asn) |
GET /as/{asn} |
PrefixIntel(net, mask) |
GET /prefix/{net}/{mask} |
DomainIntel(domain) |
GET /domain/{domain} |
CertIntel(sha256) |
GET /cert/{sha256} |
PortIntel(port) |
GET /port/{port} |
SoftwareIntel(name, version) |
GET /software/{name}[/{version}] |
RecentScans(target) |
GET /scan/{target} |
Fullscan(target, scope) |
POST /fullscan |
FullscanStatus(uuid) |
GET /fullscan/{uuid} |
FullscanResults(uuid) |
GET /fullscan/{uuid}/results |
WaitForFullscan(uuid, interval, maxWait) |
polls GET /fullscan/{uuid} |
go test -short ./... # offline unit tests (httptest server, no network)
go test ./... # adds the live smoke tests against the production APIISC License