Canary API Docs

# 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

  
        Copied!
1
2
3
4
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"
}

  
        Copied!
1
2
3
4

# 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 

  
        Copied!
1
2
3
4
Response
{
"result": "success"
}

  
        Copied!
1
2
3

# 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

  
        Copied!
1
2
3
4
5
Response
{
  "exists": true,
  "result": "success"
}

  
        Copied!
1
2
3
4

← Queries →