Custom honeypots
Custom honeypots let you build your own decoys and send what they catch to OrbitalCyber. A decoy can be a script, a canary file or account, or the AD CS decoy. Its events appear on the Honeypots page next to your sensors' honeypots, and go to the same alert recipients and webhooks. Whether you can use custom honeypots depends on your plan: they're included in the Professional plan and higher (see Subscription). Add a custom honeypot Only people who manage sensors can add, change and delete custom honeypots: the Administrator role, organisation owners and admins, and personal accounts. Go to Honeypots > Custom and select Add a custom honeypot. Enter a Name (for example Finance share canary) and, optionally, What it is. Optional: choose Alert when it goes quiet (see Heartbeats). Select Add and show token. Copy the ingest token (it starts with ohk_). It isn't shown again. The page also shows the address to send events to, and a test command for curl and for PowerShell. The token can only send events for this one custom honeypot. It can't read anything or use any other part of OrbitalCyber. Store it where only your honeypot's script can read it. New token replaces the token. The old one stops working at once. Delete removes the custom honeypot and its token. Events it already sent stay in your activity. You can have up to 50 custom honeypots. [!WARNING] Keep the traffic modest. Send at most about one request a second from each honeypot, and put several events in one request (up to 100) instead of sending one request per event. Our security controls block sources that send more, and events sent while you're blocked are lost. Honeypots should be quiet: if yours reports constantly, filter out the noise before you send. Send events Send a POST to your OrbitalCyber address followed by /api/honeypot/v1/events: Address https://orbital.saas.sageisg.com/api/honeypot/v1/events Header Authorization: Bearer ohk_… Header Content-Type: application/json Body {"events": [ … ]}, 1 to 100 events Each event: Field Required Description id yes Your identifier for the event: 1 to 128 visible ASCII characters. Send the same id and time if you resend it, and it's stored once. A Windows event record number works well, for example CA01-81234. time yes When it happened, in RFC 3339 (2026-10-15T14:03:00Z). Not in the future, and not more than 7 days ago. kind no What happened, in your words: lowercase letters, digits, ., _ or -, up to 32 characters (for example canary_opened). Default event. heartbeat is special (see below). severity no info, low, medium, high (the default) or critical. info events are recorded but never alert. src_ip no The address the activity came from. src_host no The host name it came from. actor no The account involved, for example CORP\jsmith. target no What was touched, for example a file, share or template name. detail no A sentence describing it (up to 1,000 characters). fields no Up to 10 extra key/value pairs, shown with the event. Keys: letters, digits, ., _ or -. Values: up to 300 characters. With curl: With PowerShell: Responses Status Meaning 202 Accepted: {"accepted": 2, "dropped": 0, "heartbeat": false}. 400 Nothing was stored. problems lists each invalid event, for example events[3]: time is in the future. Fix them and send the whole request again. 401 The token is missing, wrong, replaced or deleted. 403 Your plan doesn't include custom honeypots (plan_feature). 429 or connection refused You sent too much. Slow down and try again later. 503 Try again shortly. If a request fails, keep the events and send them again later. Because the id and time identify an event, a resend never creates a duplicate. Heartbeats and silence alerts A script that stops running catches nothing. To know when that happens: Send an event with "kind": "heartbeat" regularly, for example every 5 minutes. Heartbeats aren't stored or shown as activity. They only record that the honeypot is alive. Any other event counts too. On the custom honeypot, set…
OrbitalCyber documentation