# Ignore Lists

There are times when you see alerts that are generated from known, expected sources (such as scanners). In cases like this, you can add the known sources to an Ignore List which allows your Console to filter traffic and only alerts you on unexpected incidents.

# 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 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 two sources:

PDF token triggers that match our Palo Alto Wildfire annotation (opens new window)
Activity that is associated with Microsoft Defender (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

← Canarytokens Settings Integration Settings →