DNS Canary Tokens¶

DNS canary tokens provide early warning when a payload is submitted to a sandbox, analyzed by a reverse engineer, or detonated in an environment outside the target network. Each generated payload can embed a unique DNS canary domain -- if the domain is resolved from an unexpected source IP, Stentor alerts all connected operators in real time via WebSocket.

The canary system has two sides: the operator API for registering canaries and viewing trip events, and the relay-accessible endpoint that the DNS C2 server calls when it observes a canary domain resolution.

How It Works¶

sequenceDiagram
    participant Payload as Payload (Implant)
    participant DNS as Relay DNS Server
    participant API as Stentor API
    participant DB as PostgreSQL
    participant WS as Operator WebSocket

    Note over Payload,WS: Payload Generation
    API->>DB: Register canary (domain, payload_id, listener_id)
    API->>Payload: Embed canary domain in payload

    Note over Payload,WS: Canary Trip (sandbox/analyst)
    Payload->>DNS: DNS query for canary domain
    DNS->>API: POST /c2/canary/trip {domain, source_ip}
    API->>DB: Look up canary by domain
    API->>DB: Record trip event
    API->>WS: Broadcast SIEM alert to all operators
    API-->>DNS: {trip_id, status: "tripped"}

When a payload is generated, Stentor registers a canary domain and associates it with the payload and listener IDs. The canary domain is embedded in the payload binary. On first execution, the implant resolves the canary domain via DNS. If the relay's DNS server receives this query, it forwards the domain and source IP to the Stentor API, which records the trip and broadcasts an alert.

Register a Canary¶

POST /api/v1/canary/register¶

Register a DNS canary domain. Typically called during payload generation to associate a unique domain with the payload. If the domain already exists, the payload_id is updated (upsert behavior via ON CONFLICT).

Request body:

curl -s -X POST https://stentor.app/api/v1/canary/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "f47ac10b.canary.ops.local",
    "payload_id": "PAYLOAD_UUID",
    "listener_id": "LISTENER_UUID"
  }'

Response (201 Created):

{
  "id": "c3d4e5f6-...",
  "domain": "f47ac10b.canary.ops.local",
  "status": "registered"
}

Canary Trip Events¶

POST /api/v1/canary/trip (Authenticated)¶

Record a canary trip event. This endpoint is available on the authenticated API for manual trip recording or testing.

POST /api/v1/c2/canary/trip (Relay-accessible, no auth)¶

The relay's DNS server calls this endpoint when it observes a DNS query for a registered canary domain. This endpoint is on the C2 route group and does not require JWT authentication -- it is accessible from the relay's internal network.

Request body:

curl -s -X POST https://stentor.app/api/v1/canary/trip \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "f47ac10b.canary.ops.local",
    "source_ip": "198.51.100.42"
  }'

Response (200 OK):

{
  "trip_id": "a1b2c3d4-...",
  "canary_id": "c3d4e5f6-...",
  "domain": "f47ac10b.canary.ops.local",
  "source_ip": "198.51.100.42",
  "status": "tripped"
}

WebSocket Alert¶

When a canary trips, a SIEM alert is broadcast to all connected operator WebSocket sessions. The alert payload contains:

List Canaries¶

GET /api/v1/canary/list¶

List all registered canary tokens with their trip status. Canaries are returned in reverse chronological order (newest first).

curl -s https://stentor.app/api/v1/canary/list \
  -H "Authorization: Bearer $TOKEN"

Response fields:

Example response:

[
  {
    "id": "c3d4e5f6-...",
    "domain": "f47ac10b.canary.ops.local",
    "payload_id": "PAYLOAD_UUID",
    "listener_id": "LISTENER_UUID",
    "created_at": "2026-02-20T14:30:00Z",
    "tripped": true,
    "trip_count": 3
  }
]

List Trip Events¶

GET /api/v1/canary/trips¶

List all canary trip events across all canaries. Events are returned in reverse chronological order (most recent first).

curl -s https://stentor.app/api/v1/canary/trips \
  -H "Authorization: Bearer $TOKEN"

Response fields:

Example response:

[
  {
    "id": "a1b2c3d4-...",
    "canary_id": "c3d4e5f6-...",
    "domain": "f47ac10b.canary.ops.local",
    "source_ip": "198.51.100.42",
    "tripped_at": "2026-02-21T09:15:30Z"
  }
]

OPSEC Value¶

DNS canaries address a critical operational concern: detecting when your payload has been captured and analyzed outside the target environment.