gRPC API Reference

QBITEL Bridge exposes gRPC services on port 50051 for high-performance, low-latency communication between components and external integrations.

Overview

The gRPC API is used for inter-service communication between the data plane, AI Engine, and control plane. It supports unary RPCs, server streaming, and bidirectional streaming for real-time analysis.

Connection

# Default gRPC endpoint
localhost:50051

# With TLS
grpcs://qbitel-engine.qbitel-service-mesh.svc.cluster.local:50051

Service Definitions

DiscoveryService

Protocol discovery and classification operations.

service DiscoveryService {
  // Analyze traffic and discover protocols
  rpc AnalyzeTraffic(AnalyzeRequest) returns (AnalyzeResponse);

  // Classify a single message
  rpc ClassifyMessage(ClassifyRequest) returns (ClassifyResponse);

  // Stream traffic for real-time discovery
  rpc StreamAnalyze(stream TrafficChunk) returns (stream DiscoveryEvent);

  // Get discovery status
  rpc GetStatus(StatusRequest) returns (StatusResponse);
}

SecurityService

Security analysis and threat response operations.

service SecurityService {
  // Analyze a security event
  rpc AnalyzeEvent(SecurityEvent) returns (AnalysisResult);

  // Stream security events for real-time analysis
  rpc StreamEvents(stream SecurityEvent) returns (stream ThreatAlert);

  // Get security decisions
  rpc GetDecisions(DecisionQuery) returns (DecisionList);
}

PolicyService

OPA policy evaluation and management (Go control plane).

service PolicyService {
  // Evaluate a policy decision
  rpc Evaluate(PolicyInput) returns (PolicyDecision);

  // List loaded policies
  rpc ListPolicies(Empty) returns (PolicyList);

  // Reload policy bundles
  rpc ReloadPolicies(ReloadRequest) returns (ReloadResponse);
}

DeviceService

Device lifecycle and certificate management (Go management API).

service DeviceService {
  // Register a new device
  rpc Register(DeviceRegistration) returns (DeviceInfo);

  // Issue a certificate
  rpc IssueCertificate(CertRequest) returns (CertResponse);

  // Rotate device certificate
  rpc RotateCertificate(RotateRequest) returns (CertResponse);

  // Get device status
  rpc GetDeviceStatus(DeviceId) returns (DeviceStatus);
}

HealthService

service HealthService {
  // Standard gRPC health check
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}

Client Examples

Python Client

import grpc
from qbitel.proto import discovery_pb2, discovery_pb2_grpc

channel = grpc.insecure_channel('localhost:50051')
stub = discovery_pb2_grpc.DiscoveryServiceStub(channel)

request = discovery_pb2.AnalyzeRequest(
    traffic_data=[b"GET /api/users HTTP/1.1"],
    max_protocols=5
)
response = stub.AnalyzeTraffic(request)
print(f"Discovered {len(response.protocols)} protocols")

Go Client

conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
if err != nil {
    log.Fatalf("failed to connect: %v", err)
}
defer conn.Close()

client := pb.NewDiscoveryServiceClient(conn)
resp, err := client.AnalyzeTraffic(ctx, &pb.AnalyzeRequest{
    TrafficData: [][]byte{[]byte("GET /api HTTP/1.1")},
})

TLS Configuration

For production, use mTLS for all gRPC connections:

creds = grpc.ssl_channel_credentials(
    root_certificates=open('ca.pem', 'rb').read(),
    private_key=open('client-key.pem', 'rb').read(),
    certificate_chain=open('client-cert.pem', 'rb').read()
)
channel = grpc.secure_channel('qbitel-engine:50051', creds)

Next Steps