# 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