Compatible backends

You do not need Koban Fleet to run the open-source agent. Fleet is the commercial backend and control plane, but the agent can point at any backend that implements Koban Sensor Protocol v1.

This page describes the smallest honest backend that can work with the current agent.

Minimal backend

A minimal compatible backend needs to implement:

The backend does not need to implement Fleet's dashboard, alerting, billing, audit UI, or policy editor.

Enrollment model

The current agent expects bootstrap enrollment:

1. User configures sync.endpoint and sync.enrollmentToken.
2. Agent generates a P-256 private key locally.
3. Agent sends the enrollment token and base64-encoded PEM public key.
4. Backend validates the token.
5. Backend creates a device id and returns a base64-encoded PEM client certificate.

Enrollment tokens should be short-lived and narrow. Koban Fleet defaults to one use and 24 hours.

Device identity

Production backends should use mTLS for config, check-in, and sync. The certificate identity should map to exactly one tenant and device.

The request body still includes tenantId and deviceId. A backend should reject a protected request if those body IDs do not match the authenticated client certificate identity.

For local development without mTLS, a backend may accept X-Koban-Sensor-Token. Do not treat the shared token mode as equivalent to production device identity.

Config delivery

The agent has two config sources:

• Local YAML at ~/.config/koban/koban.yaml
• Remote JSON from the backend

Humans can author policy as YAML, but a compatible backend should serve remote config as canonical JSON in the configJson response field. The JSON bytes are base64-encoded in the response body.

The generation value is how the backend tells an agent that config changed. When configUpdateAvailable is true, the agent fetches the config route and applies the returned bundle if it validates locally.

Sync storage

Store events by device and localSequence, with eventId as an idempotency key.

Recommended behavior:

• If the same eventId and same content arrives again, return it as accepted with duplicate: true.
• If the same eventId maps to different content, reject it with duplicate_conflict.
• Advance acceptedThroughLocalSequence only through events the backend has durably accepted.
• Return rejected events individually so the agent can keep moving through accepted data.

The current backend validates payload bytes before accepting them. Third-party backends should do the same if they want to project inventory and findings.

Payload projection

Sync event payloads are protobuf bytes. A backend that only wants raw ingest can store the decoded bytes and hash. A backend that wants inventory and findings must decode SensorEventPayload.

Inventory payloads describe what the agent found on disk. Finding payloads describe advisory rule matches. Findings are not enforcement events.

Control hints

The sync and check-in responses contain backend hints:

certificateRenewalRequired is present in check-in responses. Certificate renewal is part of the protobuf service contract, but the current JSON route set documents enrollment, config, check-in, and sync as the v1 HTTP surface.

What to avoid

Do not ask the agent to:

• Execute remote commands
• Block installs
• Upload arbitrary files
• Scan paths outside its configured collectors
• Parse remote YAML bundles from the backend

Those are outside the open-source agent's v1 contract.

Recommended docs for your backend

If you publish a compatible backend, document:

• Which auth mode you support: mTLS, development token, or both
• How enrollment tokens are created and revoked
• How certificates are issued and rotated
• Which config fields you serve
• How long you retain raw events
• Whether you decode and project payloads
• How you handle rejected events

This keeps the open-source agent honest: users can inspect the agent code, point it at your backend, and understand exactly what data crosses the wire.