# Queries

These are a collection of endpoints that allow you to query incidents.

# Acknowledged Incidents

GET /api/v1/incidents/acknowledged

Returns all acknowledged incidents.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

node_id string
Get all incidents for a specific node
flock_id string
Get all incidents for a specific flock_id
incidents_since int
Only return incidents whose updated_id is greater than this integer. The returned feed includes a max_updated_id field if the incident list has entries
event_limit int
Specify the maximum number of event logs to be returned with the incident
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
shrink boolean
Defaults to: true
A 'true' value will remove duplicated entries (some older Consoles will have this defaulted to false, but you’d already know about it if you’re on one of those consoles)
tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

Response

JSON structure with a list of acknowledged incidents.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/acknowledged \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d limit=1 \
  -G
1
2
3
4
Response
{
  "cursor": {
    "next": "MTQzOjE0MjoxNDQ6MToxOjA6Mjoz",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/incidents/acknowledged?cursor=MTQzOjE0MjoxNDQ6MToxOjA6Mjoz&auth_token=<auth_token>",
    "prev": null,
    "prev_link": null
  },
  "feed": "Acknowledged Incidents",
  "incidents": [
    {
      "description": {
        "acknowledged": "True",
        "created": "1586338742",
        "created_std": "2020-04-08 09:39:02 UTC+0000",
        "description": "HTTP Login Attempt",
        "dst_host": "<destination_ip>",
        "dst_port": "80",
        "events": [
          {
            "HOSTNAME": "<hostname>",
            "METHOD": "POST",
            "PASSWORD": "<password>",
            "PATH": "/index.html",
            "RESPONSE": 200,
            "SKIN": "nasLogin",
            "USERAGENT": "<user_agent>",
            "USERNAME": "<username>",
            "timestamp": 1586338742,
            "timestamp_std": "2020-04-08 09:39:02 UTC+0000"
          }
        ],
        "events_count": "1",
        "ip_address": "",
        "ippers": "",
        "local_time": "2020-04-08 09:39:01",
        "logtype": "3001",
        "mac_address": "",
        "name": "ExampleBird",
        "node_id": "<node_id>",
        "notified": "False",
        "src_host": "<source_ip>",
        "src_host_reverse": "<source_hostname>",
        "src_port": "60961"
      },
      "hash_id": "<hash_id>",
      "id": "<incident_key>",
      "summary": "HTTP Login Attempt",
      "updated": "Wed, 08 Apr 2020 10:55:09 GMT",
      "updated_id": 142,
      "updated_std": "2020-04-08 10:55:09 UTC+0000",
      "updated_time": "1586343309"
    }
  ],
  "max_updated_id": 142,
  "result": "success",
  "updated": "Wed, 08 Apr 2020 10:55:09 GMT",
  "updated_std": "2020-04-08 10:55:09 UTC+0000",
  "updated_timestamp": 1586343309
}
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# All Incidents

GET /api/v1/incidents/all

Returns all incidents.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

node_id string
Get all incidents for a specific node_id
flock_id string
Get all incidents for a specific flock_id
incidents_since int
Only return incidents whose updated_id is greater than this integer. The returned feed includes a max_updated_id field if the incident list has entries
newer_than int DEPRECATED
This parameter is deprecated as it may not function as expected in all cases. Rather use incidents_since.
Timestamp used to filter returned incidents in the format yyyy-mm-dd-hh:mm:ss. All incidents created after this timestamp will be returned.
event_limit int
Specify the maximum number of event logs to be returned with the incident
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
shrink boolean
Defaults to: true
A 'true' value will remove duplicated entries (some older Consoles will have this defaulted to false, but you’d already know about it if you’re on one of those consoles)
tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

Response

JSON structure with a list of incidents.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/all \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d limit=1 \
  -G
1
2
3
4
Response
{
  "cursor": {
    "next": "MTE6MTA6MTQ0OjE6MjowOjI6NQ==",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/incidents/all?cursor=MTE6MTA6MTQ0OjE6MjowOjI6NQ%3D%3D&auth_token=<auth_token>",
    "prev": null,
    "prev_link": null
  },
  "feed": "All Incidents",
  "incidents": [
    {
      "description": {
        "acknowledged": "False",
        "created": "1586249623",
        "created_std": "2020-04-07 08:53:43 UTC+0000",
        "description": "Canarytoken triggered",
        "dst_host": "<destination_ip>",
        "dst_port": "80",
        "events": [
          {
            "canarytoken": "<token_code>",
            "dst_port": 80,
            "event_name": "",
            "headers": {
              "Accept": "*/*",
              "Accept-Encoding": "gzip, deflate",
              "Connection": "close",
              "User-Agent": ""
            },
            "src_host": "",
            "timestamp": 1586249623,
            "timestamp_std": "2020-04-07 08:53:43 UTC+0000",
            "type": "aws-id"
          }
        ],
        "events_count": "1",
        "local_time": "2020-04-07 08:53:43 (UTC)",
        "logtype": "17012",
        "memo": "Example Memo",
        "name": "N/A",
        "node_id": "<node_id>",
        "notified": "False",
        "src_host": "",
        "src_port": "0"
      },
      "hash_id": "<hash_id>",
      "id": "<incident_key>",
      "summary": "Canarytoken triggered",
      "updated": "Tue, 07 Apr 2020 08:53:43 GMT",
      "updated_id": 10,
      "updated_std": "2020-04-07 08:53:43 UTC+0000",
      "updated_time": "1586249623"
    }
  ],
  "max_updated_id": 10,
  "result": "success",
  "updated": "Tue, 07 Apr 2020 08:53:43 GMT",
  "updated_std": "2020-04-07 08:53:43 UTC+0000",
  "updated_timestamp": 1586249623
}
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# Incident History for Source IP

GET /api/v1/incidents/history/source

Returns a list of incident history for a source IP. If the `flock_id` is specified the history will be confined to the flock.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

src_ip string
The Source IP address of the incidents
flock_id string
The Flock ID of the source history

Response

JSON structure with a list of incident histories.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/history/source \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d src_ip=EXAMPLE_SOURCE_IP \
  -G
1
2
3
4
Response
{
  "incidents": [
    {
      "created": 1586260659,
      "deleted": false,
      "description": "SSH Login Attempt",
      "dst_port": 22,
      "flock_id": "flock:default",
      "key": "<incident_key>",
      "node_id": "<node_id>",
      "src_host": "<source_ip>"
    },
    ...
  ],
  "result": "success"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Search Incidents

GET /api/v1/incidents/search

Search for incidents by logtype or string. This works with pagination.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

node_id string
Only return incidents for a specific device.
flock_id string
Only return incidents for a specific flock.
filter_str string
The string used when searching for incidents. This string will attempt to match against incident details such as alert name, node_id, source IP, and destination IP
filter_logtypes string
Comma separated list of logtypes of the incidents to be returned
filter_incident_state string
Defaults to: 'unacknowledged'
Only return incidents in a specific state, one of all, unacknowledged, or acknowledged
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 filter_incident_state incidents.
cursor string
The cursor string retrieved from the cursor element returned along with a page while doing pagination

Response

JSON structure with all incidents that match the search criteria.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/search \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -d limit=1 \
  -G
1
2
3
4
5
Response
{
  "cursor": {
    "next": "Mzg6Mzk6MTY6MTowOjE6Mjo4",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/incidents/search?cursor=Mzg6Mzk6MTY6MTowOjE6Mjo4&auth_token=<auth_token>&node_id=<node_id>",
    "prev": null,
    "prev_link": null
  },
  "incident_source_counts": {
    "<source_ip>": 8
  },
  "incidents": [
    {
      "acknowledged": "False",
      "created": "1586262520",
      "created_age": "5 hours",
      "created_age_seconds": 19579.0,
      "created_printable": "Tue Apr 07 2020 12:28:40 GMT+0000 (UTC)",
      "description": "ModBus Request",
      "dst_host": "<destination_ip>",
      "dst_port": "502",
      "events_count": "1",
      "events_list": [
        1586262520000
      ],
      "events_list_printable": "Tue Apr 07 2020 12:28:40 GMT+0000 (UTC)",
      "flock_id": "flock:default",
      "hash_id": "<hash_id>",
      "host": {
        "autoreg_time": "1585947340.642295",
        "current_settings": "devicesettings:2dae15019fdbb0452a3054c3:1585973895",
        "description": "SRV Room",
        "device_id": "<device_id>",
        "device_id_hash": "<device_hash_id>",
        "device_live": "True",
        "device_version": "2.3.1",
        "first_seen": "1585947382",
        "first_seen_age": "3 days",
        "first_seen_printable": "Fri Apr 03 2020 20:56:22 GMT+0000 (UTC)",
        "first_seen_std": "2020-04-03 20:56:22 UTC+0000",
        "flock_id": "flock:default",
        "ghost": "False",
        "id": "<node_id>",
        "ignore_notifications_disconnect": "False",
        "ignore_notifications_general": "False",
        "ip_address": "<node_ip>",
        "ippers": "linux",
        "last_dns_settings_message_time": "2020-04-06 11:17:16",
        "last_heartbeat": "1586282088",
        "last_heartbeat_age": "11 seconds",
        "last_heartbeat_printable": "Tue Apr 07 2020 17:54:48 GMT+0000 (UTC)",
        "last_seen_std": "2020-04-07 17:54:48 UTC+0000",
        "live": "False",
        "local_time": "2020-04-07 17:54:47",
        "logtype": "1004",
        "mac": "00:00:00:00:00:00",
        "mac_address": "00:00:00:00:00:00",
        "name": "ExampleBird",
        "netmask": "24",
        "node_id": "<node_id>",
        "notify_after_horizon_reconnect": "False",
        "reconnect_count": "2",
        "sensor": "thinkstcanary",
        "service_count": "20",
        "update_attempts:2.3": "1",
        "uptime": "105539",
        "uptime_age": "1 day"
      },
      "incident_key": "<incident_key>",
      "ip_address": "",
      "ippers": "",
      "key": "<incident_key>",
      "local_time": "2020-04-07 12:28:39",
      "logdata": [
        {
          "FUNC_CODE": 17,
          "FUNC_NAME": "Report Slave ID",
          "UNIT_ID": 1
        }
      ],
      "logtype": "18001",
      "mac_address": "",
      "node_id": "<node_id>",
      "notified": "False",
      "previously_seen_count": 9,
      "sensor": "thinkstcanary",
      "slack_channel": "<slack_channel_id>",
      "slack_ts": "<slack_ts>",
      "src_host": "<source_ip>",
      "src_host_reverse": "<source_hostname>",
      "src_port": "55378",
      "updated": "True",
      "updated_id": 39,
      "updated_time": "1586262520",
      "updated_time_age": "5 hours",
      "updated_time_age_seconds": 19579.0,
      "updated_time_printable": "Tue Apr 07 2020 12:28:40 GMT+0000 (UTC)"
    }
  ],
  "page_number": 1,
  "result": "success",
  "total_pages": 8,
  "total_results": 8
}
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# Unacknowledged Incidents

GET /api/v1/incidents/unacknowledged

Returns all unacknowledged incidents.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

node_id string
Get all incidents for a specific node
flock_id string
Get all incidents for a specific flock_id
incidents_since int
Only return incidents whose updated_id is greater than this integer. The returned feed includes a max_updated_id field if the incident list has entries
event_limit int
Specify the maximum number of event logs to be returned with the incident
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
shrink boolean
Defaults to: true
A 'true' value will remove duplicated entries (some older Consoles will have this defaulted to false, but you’d already know about it if you’re on one of those consoles)
tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

Response

JSON structure with a list of unacknowledged incidents.

Example

curl https://EXAMPLE.canary.tools/api/v1/incidents/unacknowledged \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d limit=1 \
  -G
1
2
3
4
Response
{
  "cursor": {
    "next": "MTE6MTA6MTE6MTowOjA6Mjoy",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/incidents/unacknowledged?cursor=MTE6MTA6MTE6MTowOjA6Mjoy&auth_token=<auth_token>",
    "prev": null,
    "prev_link": null
  },
  "feed": "Unacknowledged Incidents",
  "incidents": [
    {
      "description": {
        "acknowledged": "False",
        "created": "1586249623",
        "created_std": "2020-04-07 08:53:43 UTC+0000",
        "description": "Canarytoken triggered",
        "dst_host": "<destination_ip>",
        "dst_port": "80",
        "events": [
          {
            "canarytoken": "<token_code>",
            "dst_port": 80,
            "event_name": "",
            "headers": {
              "Accept": "*/*",
              "Accept-Encoding": "gzip, deflate",
              "Connection": "close",
              "User-Agent": ""
            },
            "src_host": "",
            "timestamp": 1586249623,
            "timestamp_std": "2020-04-07 08:53:43 UTC+0000",
            "type": "aws-id"
          }
        ],
        "events_count": "1",
        "local_time": "2020-04-07 08:53:43 (UTC)",
        "logtype": "17012",
        "memo": "Example Memo",
        "name": "N/A",
        "node_id": "<node_id>",
        "notified": "False",
        "src_host": "",
        "src_port": "0"
      },
      "hash_id": "<hash_id>",
      "id": "<incident_key>",
      "summary": "Canarytoken triggered",
      "updated": "Tue, 07 Apr 2020 08:53:43 GMT",
      "updated_id": 10,
      "updated_std": "2020-04-07 08:53:43 UTC+0000",
      "updated_time": "1586249623"
    }
  ],
  "max_updated_id": 10,
  "result": "success",
  "updated": "Tue, 07 Apr 2020 08:53:43 GMT",
  "updated_std": "2020-04-07 08:53:43 UTC+0000",
  "updated_timestamp": 1586249623
}
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59