# Outside Birds

Canaries marked as Outside Birds can be exposed to the public internet without the risk of missing the high quality signals from your local Canaries.

The major difference between an Outside Bird and a normal Canary is how they generate alerts.

Outside Bird alerts only store the IP address of the attacker and a tally of the number of times any service was targeted. These alerts will not appear on the Canary Console as an incident and are instead accessed from the Canary modal or the API.

Additionally, Outside Birds do not send alert notifications (Email, SMS etc) to users, with the exception of separately configured webhooks.

# Alert Count Summary

GET /api/v1/incidents/outside_bird/summary

Retrieves a summary of alert counts for the Canary.

Required Parameters

auth_token string
A valid auth token
node_id string
The node_id of a device

Response

A JSON Structure of alert count information.

Example

    Response
    {
        "count": 2099,
        "result": "success"
    }
    
    1
    2
    3
    4

    # Incidents Count Per Service

    GET /api/v1/incidents/outside_bird/services/count

    Retrieve a list of targeted service counts.

    Required Parameters

    auth_token string
    A valid auth token
    node_id string
    The node_id of a device

    Response

    A JSON structure with the counts for each targeted service.

    Example

      Response
      {
        "counts": [
          {
            "count": 2694,
            "service": "SSH Login Attempt"
          },
          {
            "count": 432,
            "service": "SIP Request"
          },
          {
            "count": 370,
            "service": "Telnet Login Attempt"
          },
        ],
        "result": "success"
      }
      
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17

      # Outside Bird Alerts

      GET /api/v1/incidents/outside_bird/search

      Retrieve a paginated list of Outside Bird Alerts.

      Required Parameters

      auth_token string
      A valid auth token

      Optional Parameters

      node_ids string
      A comma-separated list of device node_ids
      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

      Response

      A JSON structure with a paginated list of Outside Bird Alert Source IP addresses and cursor object.

      Example

        Response
        {
          "cursor": {
            "next": "MToxMDM5OTcwMTY6MTAwOjU6MjoyMg==",
            "next_link": "https://EXAMPLE.canary.tools/api/v1/incidents/outside_bird/search?cursor=MToxMDM5OTcwMTY6MTAwOjU6MjoyMg%3D%3D&auth_token=EXAMPLE_AUTH_TOKEN&node_ids=EXAMPLE_NODE_IDS",
            "prev": null,
            "prev_link": null
          },
          "page_num": 1,
          "page_total": 1,
          "result": "success",
          "src_ips": [
            {
              "count": 7,
              "incident_counts": {
                "SSH Login Attempt": 7
              },
              "ip_address": "EXAMPLE_IP_ADDRESS",
              "node_id": "EXAMPLE_NODE_ID"
            },
            {
              "count": 1,
              "incident_counts": {
                "SSH Login Attempt": 1
              },
              "ip_address": "EXAMPLE_IP_ADDRESS",
              "node_id": "EXAMPLE_NODE_ID"
            },
          ]
        }
        
        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

        # Delete Outside Bird Alert

        DELETE /api/v1/incident/outside_bird/delete

        Deletes an Outside Bird Alert

        Required Parameters

        auth_token string
        A valid auth token
        node_id string
        The node_id of a device
        src_ip string
        The IP address of the alert

        Response

        JSON structure with result indicator

        Example

          Response
          {
            "result": "success",
          }
          
          1
          2
          3

          # Delete All Outside Bird Alerts

          DELETE /api/v1/incidents/outside_bird/delete

          Deletes all Outside Bird Alerts for a Canary

          Required Parameters

          auth_token string
          A valid auth token
          node_id string
          The node_id of a device

          Response

          JSON structure with result indicator and the number of source IPs from deleted incidents.

          Example

            Response
            {
              "deleted": 2, 
              "result": "success"
            }
            
            1
            2
            3
            4

            # Make a Canary an Outside Bird

            POST /api/v1/device/outside_bird/enable

            Makes a Canary an Outside Bird

            Required Parameters

            auth_token string
            A valid auth token
            node_id string
            The node_id of a device

            Response

            JSON structure with result indicator

            Example

              Response
              {
                "result": "success",
              }
              
              1
              2
              3

              # Make an Outside Bird a Standard Canary

              POST /api/v1/device/outside_bird/disable

              Makes an Outside Bird a standard Canary

              Required Parameters

              auth_token string
              A valid auth token
              node_id string
              The node_id of a device

              Response

              JSON structure with result indicator

              Example

                Response
                {
                  "result": "success",
                }
                
                1
                2
                3

                # Download Outside Bird Alerts

                GET /api/v1/incidents/outside_bird/download/json

                Downloads Outside Bird Alerts

                Required Parameters

                auth_token string
                A valid auth token
                node_id string
                The node_id of a device
                email string
                If their are more than 50,000 alerts we will email an archive of the alerts after ~15 minutes.

                Response

                An archive of the alerts.

                Example

                  Response
                  {
                    "result": "success",
                  }
                  
                  1
                  2
                  3

                  # Webhooks

                  Outside Birds do not send notifications to the same channels that regular birds do - due to the large quantity of alerts they generate.

                  If you need a way to consume the alerts in real-time, add a hook and we'll send you alerts as they arrive!

                  # List Outside Bird Webhooks

                  GET /api/v1/device/outside_bird/webhooks

                  List all Outside Bird Webhooks

                  Required Parameters

                  auth_token string
                  A valid auth token

                  Response

                  JSON structure with a list of Outside Bird webhooks

                  Example

                    Response
                    {
                        "result": "success",
                        "webhooks": [
                            "https://siem.example.com/outside-bird-alerts",
                        ]
                    }
                    
                    1
                    2
                    3
                    4
                    5
                    6

                    # Add Outside Bird Webhook

                    POST /api/v1/device/outside_bird/webhooks/add

                    Adds an Outside Bird Webhook

                    Required Parameters

                    auth_token string
                    A valid auth token
                    url string
                    The URL of the configured webhook

                    Response

                    JSON structure with a result indicator

                    Example

                      Response
                      {
                        "result": "success",
                      }
                      
                      1
                      2
                      3

                      # Remove Outside Bird Webhook

                      DELETE /api/v1/device/outside_bird/webhooks/remove

                      Removes an Outside Bird Webhook

                      Required Parameters

                      auth_token string
                      A valid auth token
                      url string
                      The URL of the configured webhook

                      Response

                      JSON structure with a result indicator

                      Example

                        Response
                        {
                          "result": "success",
                        }
                        
                        1
                        2
                        3

                        # Test Outside Bird Webhook

                        POST /api/v1/device/outside_bird/webhooks/test

                        Tests an Outside Bird Webhook

                        Required Parameters

                        auth_token string
                        A valid auth token
                        url string
                        The URL of the configured webhook

                        Response

                        JSON structure with a result indicator

                        Example

                          Response
                          {
                            "result": "success",
                          }
                          
                          1
                          2
                          3