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.
Alert Count Summary GET /api/v1/incidents/outside_bird/summary
Retrieves a summary of alert counts for the Canary.
Show details
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
1 2 3 4
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"count" : 2099 ,
"result" : "success"
}
1 2 3 4
Incidents Count Per Service GET /api/v1/incidents/outside_bird/services/count
Retrieve a list of targeted service counts.
Show details
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
1 2 3 4
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"counts" : [
{
"count" : 2694 ,
"service" : "SSH Login Attempt"
} ,
{
"count" : 432 ,
"service" : "SIP Request"
} ,
{
"count" : 370 ,
"service" : "Telnet Login Attempt"
} ,
] ,
"result" : "success"
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
Outside Bird Alerts GET /api/v1/incidents/outside_bird/search
Retrieve a paginated list of Outside Bird Alerts.
Show details
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
1 2 3 4
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"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"
} ,
]
}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
Delete Outside Bird Alert DELETE /api/v1/incident/outside_bird/delete
Deletes an Outside Bird Alert
Show details
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
1 2 3 4
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12 13
{
"result" : "success" ,
}
1 2 3
Delete All Outside Bird Alerts DELETE /api/v1/incidents/outside_bird/delete
Deletes all Outside Bird Alerts for a Canary
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"deleted" : 2 ,
"result" : "success"
}
1 2 3 4
Make a Canary an Outside Bird POST /api/v1/device/outside_bird/enable
Makes a Canary an Outside Bird
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
}
1 2 3
Make an Outside Bird a Standard Canary POST /api/v1/device/outside_bird/disable
Makes an Outside Bird a standard Canary
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
}
1 2 3
Download Outside Bird Alerts GET /api/v1/incidents/outside_bird/download/json
Downloads Outside Bird Alerts
Show details
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
1 2 3 4
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)
1 2 3 4 5 6 7 8 9 10 11 12 13 14
{
"result" : "success" ,
}
1 2 3
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
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success" ,
"webhooks" : [
"https://siem.example.com/outside-bird-alerts" ,
]
}
1 2 3 4 5 6
Add Outside Bird Webhook POST /api/v1/device/outside_bird/webhooks/add
Adds an Outside Bird Webhook
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
}
1 2 3
Remove Outside Bird Webhook DELETE /api/v1/device/outside_bird/webhooks/remove
Removes an Outside Bird Webhook
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
}
1 2 3
Test Outside Bird Webhook POST /api/v1/device/outside_bird/webhooks/test
Tests an Outside Bird Webhook
Show details
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
1 2 3
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( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success" ,
}
1 2 3
Last Updated: 5/10/2022, 11:41:29 AM
