Personalities

These are a collection of endpoints that allow you to interact with Bird personalities. This includes the built-in Bird personalities as well as custom personalities that you create.

Endpoints

GET /api/v1/personalities/list

DELETE /api/v1/personalities/delete

GET /api/v1/device/custompersonality/exists

List Personalities

GET /api/v1/personalities/list

Returns a list of available Bird personalities for a specified version or Bird (node_id).

Required Parameters

auth_token string

A valid auth token

Optional Parameters

node_id string

A valid Canary node_id

version string

A valid version number

include_settings boolean

Defaults to: true

Whether to include the settings object for each personality

as_string boolean

Defaults to: true

Whether to dump the personalities object to a string

TIP

Either node_id or version is required.

Response

JSON structure with personalities for the specified node id's version or specified version.

Example

curl https://EXAMPLE.canary.tools/api/v1/personalities/list \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/personalities/list'

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

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

print(r.json())

Response

{
  "personalities": "[{\"list\": [{\"settings\": {}, \"name\": \"\", \"desc\": \"Pick One\"}, {\"settings\": {\"device.ippers\": \"linux\"}, \"name\": \"bare\", \"desc\": \"Bare Canary (no services)\"}, {\"settings\": {\"http.enabled\": true, \"tftp.enabled\": true, \"smb.enabled\": true, \"vnc.enabled\": true, \"sip.enabled\": true, \"tcpbanner_1.enabled\": true, \"ftp.enabled\": true, \"telnet.enabled\": true, \"httpproxy.enabled\": true, \"git.enabled\": true, \"ntp.enabled\": true, \"redis.enabled\": true, \"device.ippers\": \"linux\", \"tcpbanner.enabled\": true, \"mssql.enabled\": true, \"modbus.enabled\": true, \"ssh.enabled\": true, \"mysql.enabled\": true}, \"name\": \"merry-christmas\", \"desc\": \"Christmas Tree (all services)\"}], \"name\": \"General\"}, {\"list\": [{\"settings\": {\"vnc.enabled\": true, \"smb.sharename\": \"Documents\", \"smb.netbiosname\": \"OFFICESHARE\", \"smb.enabled\": true, \"device.mac_prefix\": \"00:03:93\", \"telnet.authentication_failed_prompt\": \"\\\\nLogin incorrect\\\\n\\\\n\", \"telnet.enabled\": false, \"smb.serverstring\": \"Office Share\", \"smb.sharecomment\": \"Office Document Share\", \"device.ippers\": \"osx\", \"ssh.version\": \"SSH-2.0-OpenSSH_7.4\", \"telnet.password_prompt\": \"Password:\", \"telnet.user_prompt\": \"login: \", \"ssh.enabled\": true, \"ssh.port\": 22, \"vnc.port\": 5900, \"telnet.banner\": \"Darwin/BSD\\\\r\\\\n\\\\r\\\\n\"}, \"name\": \"osx-fileshare\", \"desc\": \"Mac OS X Fileshare\"}], \"name\": \"Apple\"}, {\"list\": [], \"name\": \"Custom\"}]"
  "result": "success"
}

Delete Personality

DELETE /api/v1/personalities/delete

Delete a specified custom personality.

Required Parameters

auth_token string

A valid auth token

personality string

Custom personality to delete

flock_id string

Specify the Flock which has the custom personality you would like to delete.

WARNING

You cannot delete built-in personalities. Only custom personalities that you've saved can be deleted.

Response

A JSON message with a result indicator.

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/personalities/delete \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d personality=EXAMPLE_PERSONALITY \
  -d flock_id=EXAMPLE_FLOCK_ID 

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'personality': 'EXAMPLE_PERSONALITY',
  'flock_id': 'EXAMPLE_FLOCK_ID'
}

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

print(r.json())

Response

{
"result": "success"
}

Bird Custom Personality Exists

GET /api/v1/device/custompersonality/exists

Checks if a custom personality exists for a specified Bird.

Required Parameters

auth_token string

A valid auth token

node_id string

A valid Canary node_id

name string

The name of the Custom personality

Response

A JSON message with a result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/device/custompersonality/exists \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -d name=EXAMPLE_CUSTOM_PERSONALITY_NAME \
  -G

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/device/custompersonality/exists'

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

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

print(r.json())

Response

{
  "exists": true,
  "result": "success"
}