Outside Birds

Canaries marked as Outside Birds can be exposed to the public internet without the risk of missing the high quality signals from your local Canaries.

The major difference between an Outside Bird and a normal Canary is how they generate alerts.

Outside Bird alerts only store the IP address of the attacker and a tally of the number of times any service was targeted. These alerts will not appear on the Canary Console as an incident and are instead accessed from the Canary modal or the API.

Additionally, Outside Birds do not send alert notifications (Email, SMS etc) to users, with the exception of separately configured webhooks.

Endpoints

GET /api/v1/incidents/outside_bird/summary

GET /api/v1/incidents/outside_bird/services/count

GET /api/v1/incidents/outside_bird/search

DELETE /api/v1/incident/outside_bird/delete

DELETE /api/v1/incidents/outside_bird/delete

POST /api/v1/device/outside_bird/enable

POST /api/v1/device/outside_bird/disable

GET /api/v1/incidents/outside_bird/download/json

GET /api/v1/device/outside_bird/webhooks

POST /api/v1/device/outside_bird/webhooks/add

DELETE /api/v1/device/outside_bird/webhooks/remove

POST /api/v1/device/outside_bird/webhooks/test

Alert Count Summary

GET /api/v1/incidents/outside_bird/summary

Retrieves a summary of alert counts for the Canary.

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

Response

A JSON Structure of alert count information.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/summary \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/summary'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.get(url, params=payload)

print(r.json())

Response

{
    "count": 2099,
    "result": "success"
}

Incidents Count Per Service

GET /api/v1/incidents/outside_bird/services/count

Retrieve a list of targeted service counts.

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

Response

A JSON structure with the counts for each targeted service.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/services/count \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/services/count'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.get(url, params=payload)

print(r.json())

Response

{
  "counts": [
    {
      "count": 2694,
      "service": "SSH Login Attempt"
    },
    {
      "count": 432,
      "service": "SIP Request"
    },
    {
      "count": 370,
      "service": "Telnet Login Attempt"
    },
  ],
  "result": "success"
}

Outside Bird Alerts

GET /api/v1/incidents/outside_bird/search

Retrieve a paginated list of Outside Bird Alerts.

Required Parameters

auth_token string

A valid auth token

Optional Parameters

node_ids string

A comma-separated list of device node_ids

limit int

Parameter used to initiate cursor pagination. The limit is used to specify the page sizes returned when iterating through the pages representing all incidents

cursor string

The cursor string retrieved from the cursor element returned along with a page while doing pagination

Response

A JSON structure with a paginated list of Outside Bird Alert Source IP addresses and cursor object.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/search \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_ids=EXAMPLE_NODE_IDS \
  -G

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/search'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_ids': 'EXAMPLE_NODE_IDS'
}

r = requests.get(url, params=payload)

print(r.json())

Response

{
  "cursor": {
    "next": "MToxMDM5OTcwMTY6MTAwOjU6MjoyMg==",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/search?cursor=MToxMDM5OTcwMTY6MTAwOjU6MjoyMg%3D%3D&auth_token=EXAMPLE_AUTH_TOKEN&node_ids=EXAMPLE_NODE_IDS",
    "prev": null,
    "prev_link": null
  },
  "page_num": 1,
  "page_total": 1,
  "result": "success",
  "src_ips": [
    {
      "count": 7,
      "incident_counts": {
        "SSH Login Attempt": 7
      },
      "ip_address": "EXAMPLE_IP_ADDRESS",
      "node_id": "EXAMPLE_NODE_ID"
    },
    {
      "count": 1,
      "incident_counts": {
        "SSH Login Attempt": 1
      },
      "ip_address": "EXAMPLE_IP_ADDRESS",
      "node_id": "EXAMPLE_NODE_ID"
    },
  ]
}

Delete Outside Bird Alert

DELETE /api/v1/incident/outside_bird/delete

Deletes an Outside Bird Alert

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

src_ip string

The IP address of the alert

Response

JSON structure with result indicator

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/incident/outside_bird/delete \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -d src_ip=EXAMPLE_SRC_IP

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/incident/outside_bird/delete'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID',
  'src_ip': 'EXAMPLE_SRC_IP'
}

r = requests.delete(url, data=payload)

print(r.json())

Response

{
  "result": "success",
}

Delete All Outside Bird Alerts

DELETE /api/v1/incidents/outside_bird/delete

Deletes all Outside Bird Alerts for a Canary

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

Response

JSON structure with result indicator and the number of source IPs from deleted incidents.

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/delete \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/delete'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.delete(url, data=payload)

print(r.json())

Response

{
  "deleted": 2, 
  "result": "success"
}

Make a Canary an Outside Bird

POST /api/v1/device/outside_bird/enable

Makes a Canary an Outside Bird

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

Response

JSON structure with result indicator

Example

curl https://EXAMPLE.canary.tools/api/v1/device/outside_bird/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/outside_bird/enable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.post(url, params=payload)

print(r.json())

Response

{
  "result": "success",
}

Make an Outside Bird a Standard Canary

POST /api/v1/device/outside_bird/disable

Makes an Outside Bird a standard Canary

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

Response

JSON structure with result indicator

Example

curl https://EXAMPLE.canary.tools/api/v1/device/outside_bird/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/outside_bird/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.post(url, params=payload)

print(r.json())

Response

{
  "result": "success",
}

Download Outside Bird Alerts

GET /api/v1/incidents/outside_bird/download/json

Downloads Outside Bird Alerts

Required Parameters

auth_token string

A valid auth token

node_id string

The node_id of a device

email string

If their are more than 50,000 alerts we will email an archive of the alerts after ~15 minutes.

Response

An archive of the alerts.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/download/json \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G -O -J

import requests
import re

url = 'https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/download/json'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'node_id': 'EXAMPLE_NODE_ID'
}

r = requests.get(url, params=payload)
filename = re.findall("filename=(.+)", r.headers["Content-Disposition"])[0]
with open(filename, 'wb') as f:
    f.write(r.content)

Response

{
  "result": "success",
}

Webhooks

Outside Birds do not send notifications to the same channels that regular birds do - due to the large quantity of alerts they generate.

If you need a way to consume the alerts in real-time, add a hook and we'll send you alerts as they arrive!

List Outside Bird Webhooks

GET /api/v1/device/outside_bird/webhooks

List all Outside Bird Webhooks

Required Parameters

auth_token string

A valid auth token

Response

JSON structure with a list of Outside Bird webhooks

Example

curl https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.get(url, params=payload)

print(r.json())

Response

{
    "result": "success",
    "webhooks": [
        "https://siem.example.com/outside-bird-alerts",
    ]
}

Add Outside Bird Webhook

POST /api/v1/device/outside_bird/webhooks/add

Adds an Outside Bird Webhook

Required Parameters

auth_token string

A valid auth token

url string

The URL of the configured webhook

Response

JSON structure with a result indicator

Example

curl https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks/add'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'url': 'EXAMPLE_URL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success",
}

Remove Outside Bird Webhook

DELETE /api/v1/device/outside_bird/webhooks/remove

Removes an Outside Bird Webhook

Required Parameters

auth_token string

A valid auth token

url string

The URL of the configured webhook

Response

JSON structure with a result indicator

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d url=EXAMPLE_URL

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks/remove'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'url': 'EXAMPLE_URL'
}

r = requests.delete(url, data=payload)

print(r.json())

Response

{
  "result": "success",
}

Test Outside Bird Webhook

POST /api/v1/device/outside_bird/webhooks/test

Tests an Outside Bird Webhook

Required Parameters

auth_token string

A valid auth token

url string

The URL of the configured webhook

Response

JSON structure with a result indicator

Example

curl https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks/test \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d update_tag=EXAMPLE_URL

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/outside_bird/webhooks/test'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'url': 'EXAMPLE_URL'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success",
}