# Ignore Lists

# Default Ignore Lists

You can add IP addresses and optional destination ports to this list to ignore traffic that originates from the specified IP. If a ports are specified, we'll only ignore the traffic from the specified IP to the destination port.

# Ignore IP and Port

POST /api/v1/settings/whitelist_ip_port

Ignore Traffic from an IP and (optional) Port.

Required Parameters

auth_token string
A valid auth token
src_ip string
The source IP to ignore

Optional Parameters

dst_port int
The destination port to ignore

Response

A JSON structure with result indicator.

Example

    Response
    {
      "message": "Whitelist added",
      "result": "success"
    }
    
    1
    2
    3
    4

    # Disable Ignore List

    POST /api/v1/settings/whitelisting/disable

    Disable the ignore list.

    Required Parameters

    auth_token string
    A valid auth token

    Response

    A JSON structure with result indicator.

    Example

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

      # Enable Ignore List

      POST /api/v1/settings/whitelisting/enable

      Enable the ignore list.

      Required Parameters

      auth_token string
      A valid auth token

      Response

      A JSON structure with result indicator.

      Example

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

        # Remove an Ignored IP

        POST /api/v1/settings/whitelisting/remove_whitelist_ip

        Remove an ignored IP from the ignore list.

        Required Parameters

        auth_token string
        A valid auth token
        src_ip string
        IP address to remove from the list

        Response

        A JSON structure with result indicator.

        Example

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

          # Set Ignore List

          POST /api/v1/settings/whitelisting/whitelist_ips

          Set a list of IPs to ignore.

          Required Parameters

          auth_token string
          A valid auth token

          Optional Parameters

          whitelist_ips string
          Newline separated list of IP addresses to ignore
          clear boolean
          Clear the ignore list

          TIP

          At least one of the optional parameters is required.

          TIP

          You can add comments to your list of ignored IPs by prefixing a line with '#'

          For example, to set your ignore list to the below:

          # test comment
          1.2.3.4
          10.10.10.10
          
          1
          2
          3

          You would send through:

          -d $'# test comment\n1.2.3.4\n10.10.10.10'

          Response

          A JSON structure with result indicator.

          Example

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

            # Hostname Ignore Lists

            If you want to ignore traffic from a specific, known hostname, you can use these endpoints.

            # Disable Hostname Ignore List

            POST /api/v1/settings/ignore_hostnames/disable

            Disable Ignoring by Hostname.

            Required Parameters

            auth_token string
            A valid auth token

            Response

            JSON structure with result indicator.

            Example

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

              # Enable Hostname Ignore List

              POST /api/v1/settings/ignore_hostnames/enable

              Enable Ignoring by Hostname.

              Required Parameters

              auth_token string
              A valid auth token

              Response

              JSON structure with result indicator.

              Example

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

                # Set Hostname Ignore List

                POST /api/v1/settings/ignore_hostnames

                Sets the hostname ignore list.

                Required Parameters

                auth_token string
                A valid auth token

                Optional Parameters

                hostnames string
                The list of hostnames separated by a newline character
                clear boolean
                If true, clears the ignore list

                Response

                JSON structure with result indicator.

                Example

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

                  # Source Port Ignore Lists

                  If you want to ignore traffic that originates from a known source port, you can use these endpoints.

                  # Disable Source Port Ignore List

                  POST /api/v1/settings/ignorelist_src_port/disable

                  Disable ignoring by source port.

                  Required Parameters

                  auth_token string
                  A valid auth token

                  Response

                  JSON structure with result indicator.

                  # Enable Source Port Ignore List

                  POST /api/v1/settings/ignorelist_src_port/enable

                  Enable ignoring by source port.

                  Required Parameters

                  auth_token string
                  A valid auth token

                  Response

                  JSON structure with result indicator.

                  Example

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

                    # Set Source Port Ignore List

                    POST /api/v1/settings/ignorelist_src_port

                    Sets the source port ignore list.

                    Required Parameters

                    auth_token string
                    A valid auth token

                    Optional Parameters

                    ignorelist_src_port_ips string
                    The list of IPs to ignore, separated by a newline character
                    clear boolean
                    If true, clears the ignore list

                    Response

                    JSON structure with result indicator.

                    Example

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

                      # Test Ignore Lists

                      Using the below endpoints, you can easily test if given hostnames and IP addresses are already ignored on your Console.

                      # Test if Hostname is Ignored

                      GET /api/v1/settings/is_hostname_whitelisted

                      Test if a given hostname has been ignored.

                      Required Parameters

                      auth_token string
                      A valid auth token
                      hostname string
                      The source hostname to test

                      Optional Parameters

                      dst_port int
                      The destination port to test

                      Response

                      A JSON structure with the test result.

                      Example

                        Response
                        {
                          "is_hostname_whitelisted": true,
                          "is_whitelist_enabled": true
                        }
                        
                        1
                        2
                        3
                        4

                        # Test if IP is Ignored

                        GET /api/v1/settings/is_ip_ignored

                        Test if a given IP address has been ignored.

                        Required Parameters

                        auth_token string
                        A valid auth token
                        src_ip string
                        The source IP to test

                        Optional Parameters

                        dst_port int
                        The destination port to test

                        Response

                        A JSON structure with the test result.

                        Example

                          Response
                          {
                            "is_ip_whitelisted": true,
                            "is_whitelist_enabled": true
                          }
                          
                          1
                          2
                          3
                          4

                          # Annotation-based Ignore Lists

                          You can ignore incidents based on matched annotations. Currently, this is only available for PDF token triggers that match our Palo Alto Wildfire annotation (you can read more about it here (opens new window)).

                          # Disable Annotation Ignore List

                          POST /api/v1/settings/ignored_annotations/disable

                          Disable ignoring based on alert annotations.

                          Required Parameters

                          auth_token string
                          A valid auth token

                          Response

                          JSON structure with result indicator.

                          Example

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

                            # Enable Annotation Ignore List

                            POST /api/v1/settings/ignored_annotations/enable

                            Enable ignoring based on alert annotations.

                            Required Parameters

                            auth_token string
                            A valid auth token

                            Response

                            JSON structure with result indicator.

                            Example

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

                              # Fetch Annotation Ignore List

                              GET /api/v1/settings/ignored_annotations

                              Fetch the list of ignored annotations.

                              Required Parameters

                              auth_token string
                              A valid auth token

                              Response

                              JSON structure with a list of ignored annotations.

                              Example

                                Response
                                {
                                  "ignored_annotations": [
                                    {
                                      "kb_link": "https://help.canary.tools/hc/en-gb/articles/360013051378",
                                      "name": "palo_alto_pdf_token_trigger",
                                      "nice_name": "Palo Alto WildFire PDF Scan",
                                      "text": "This looks like it was automatically triggered by Palo Alto's WildFire service."
                                    }
                                  ],
                                  "result": "success"
                                }
                                
                                1
                                2
                                3
                                4
                                5
                                6
                                7
                                8
                                9
                                10
                                11

                                # Ignore an Alert Annotation

                                POST /api/v1/settings/ignored_annotations/ignore

                                Add an alert annotation to the ignore list.

                                Required Parameters

                                auth_token string
                                A valid auth token
                                annotation string
                                The name of a valid annotation to ignore

                                Response

                                Example

                                  Response
                                  {
                                    "message": "Annotation successfully ignored",
                                    "result": "success"
                                  }
                                  
                                  1
                                  2
                                  3
                                  4

                                  # Remove an Ignored Alert Annotation

                                  DELETE /api/v1/settings/ignored_annotations/remove

                                  Remove an alert annotation from the ignore list.

                                  Required Parameters

                                  auth_token string
                                  A valid auth token
                                  annotation string
                                  The name of a valid annotation to remove

                                  Response

                                  JSON structure with result indicator.

                                  Example

                                    Response
                                    {
                                      "message": "Annotation removed successfully",
                                      "result": "success"
                                    }
                                    
                                    1
                                    2
                                    3
                                    4

                                    # Check if Annotation is Ignored

                                    GET /api/v1/settings/ignored_annotations/is_annotation_ignored

                                    Check if a supplied annotation is ignored.

                                    Required Parameters

                                    auth_token string
                                    A valid auth token
                                    annotation string
                                    The name of a valid annotation to check

                                    Response

                                    JSON structure with a boolean indicator.

                                    Example

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

                                      # Get Ignored Incident Count

                                      GET /api/v1/settings/ignored_annotations/incidents/count

                                      Return the count of incidents that have been ignored for an annotation.

                                      Required Parameters

                                      auth_token string
                                      A valid auth token
                                      annotation string
                                      The name of a valid annotation to check

                                      Response

                                      JSON structure with a count of ignored incidents.

                                      Example

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

                                        # Fetch Ignored Annotations

                                        GET /api/v1/settings/ignored_annotations/incidents

                                        Return a paginated list of incidents ignored by an annotation.

                                        Required Parameters

                                        auth_token string
                                        A valid auth token
                                        annotation string
                                        The name of a valid annotation to check

                                        Optional Parameters

                                        page int
                                        The result page to return

                                        Response

                                        JSON structure with a list of ignored incidents, as well as the total incident count and current page, previous page and next page links.

                                        Example

                                          Response
                                          {
                                            "ignored_incidents": [
                                              {
                                                "acknowledged": false,
                                                "created": 1612270411,
                                                "created_std": "2021-02-02 12:53:31 UTC+0000",
                                                "description": "Canarytoken triggered",
                                                "dst_host": "1.1.1.1",
                                                "dst_port": 80,
                                                "events": [
                                                  ...
                                                ],
                                                "events_count": 1,
                                                "events_list": "1612270411",
                                                "local_time": "2021-02-02 12:53:31 (UTC)",
                                                "logtype": 16008,
                                                "matched_annotations": {
                                                  "palo_alto_pdf_token_trigger": [
                                                    "This looks like it was automatically triggered by Palo Alto's WildFire service.",
                                                    "https://help.canary.tools/hc/en-gb/articles/360013051378"
                                                  ]
                                                },
                                                "memo": "Example Annotation",
                                                "name": "Acrobat PDF",
                                                "node_id": "<node_id>",
                                                "notified": false,
                                                "src_host": "<src_ip>",
                                                "src_port": 0
                                              },
                                              ...
                                            ],
                                            "next_page": 2,
                                            "page": 1,
                                            "prev_page": null,
                                            "result": "success",
                                            "total_incidents": 24
                                          }
                                          
                                          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