gRPC Services
The OrbGuard Labs gRPC threat-intelligence interface — its proto contract, current availability, and roadmap. Use the REST API and WebSocket stream today.
gRPC Services
A high-throughput, strongly-typed gRPC interface for bulk indicator checking and streaming threat feeds is being built on top of the OrbGuard Labs engine. The protobuf contract is defined and the gRPC health service is live; the threat-intelligence RPCs are on the roadmap. Until they ship, the REST API and WebSocket stream deliver the same capabilities.
Availability
The ThreatIntelligenceService gRPC methods are not yet reachable in production. The gRPC server runs and its health-check service responds, but the threat-intelligence service is intentionally reported as NOT_SERVING until the generated protobuf bindings are wired in. For anything you need today, use the equivalent REST endpoints and the real-time WebSocket stream. This page documents the contract so integrators can prepare ahead of GA.
Why gRPC
gRPC is designed for the highest-volume integration: OrbNet and OrbMesh VPN servers checking domains against the threat database on every DNS query, and streaming new indicators to the fleet in real time. It offers strongly-typed messages, HTTP/2 multiplexing, and server-side streaming that REST cannot match for these hot paths.
Bulk Indicator Checks
Check many domains, IPs, hashes, and URLs in a single typed request — built for VPN DNS filtering at line rate.
Streaming Threat Feed
Subscribe to new indicators as they are published, so VPN servers update their blocklists the moment a threat is confirmed.
Service Contract
The interface is defined in proto/threatintel/v1/threat_intelligence.proto, package threatintel.v1, service ThreatIntelligenceService. Nine RPCs are specified:
| RPC | Type | Purpose |
|---|---|---|
CheckIndicators | Unary | Check whether a batch of indicators is malicious (DNS filtering) |
GetThreatStats | Unary | Aggregated threat statistics |
StreamNewThreats | Server stream | Stream new threats in real time to VPN servers |
ShouldBlockDomain | Unary | Decide whether a single domain should be blocked |
ReportNetworkThreat | Unary | Report a threat detected from VPN traffic analysis |
GetIndicator | Unary | Retrieve a single indicator by value |
ListIndicators | Unary | List indicators with filtering |
GetCampaign | Unary | Retrieve campaign details |
ListCampaigns | Unary | List all campaigns |
REST Equivalents Available Now
Every RPC above maps to a REST endpoint you can call today: CheckIndicators → POST /api/v1/intelligence/check/batch, ShouldBlockDomain → POST /api/v1/orbnet/dns/block, StreamNewThreats → the wss://guard.orbai.world/ws/threats WebSocket, ListCampaigns → GET /api/v1/campaigns, and so on. Build against REST now and switch the hot paths to gRPC when it reaches GA.
Health Check (Live Today)
The standard gRPC health-checking protocol (grpc.health.v1.Health) is already served. It reports the overall server as SERVING and the threatintel.v1.ThreatIntelligenceService as NOT_SERVING until the service RPCs are wired in — giving integrators a programmatic readiness signal.
# Using grpcurl against the gRPC health service
grpcurl -d '{"service": "threatintel.v1.ThreatIntelligenceService"}' \
guard.orbai.world:443 grpc.health.v1.Health/Check
# => { "status": "NOT_SERVING" } (until GA)
grpcurl -d '{"service": ""}' \
guard.orbai.world:443 grpc.health.v1.Health/Check
# => { "status": "SERVING" } (server is up)Watch the Health Status
Poll the health check (or use grpc.health.v1.Health/Watch) for the threatintel.v1.ThreatIntelligenceService service. When it transitions from NOT_SERVING to SERVING, the threat-intelligence RPCs are available and you can cut over from REST.
Integrate Threat Intelligence Today
The REST API and WebSocket stream already cover bulk indicator checks, domain-block decisions, and real-time threat feeds. Start there and adopt gRPC for the hottest paths when it ships.