# 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

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

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

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

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

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

← Actions Incident Objects →