Safelisting Guide¶

Safelisting lets you exclude known-good traffic from the AC-Hunter Dashboard so you can focus on genuinely suspicious connections. Safelisted connections are hidden by default but can be revealed at any time using the Dashboard filter toggle.

This page covers safelist entry types, how to create and manage entries, importing and exporting, and upgrading safelists from AC-Hunter v6.

How Safelisting Works¶

When you add a safelist entry, AC-Hunter matches it against all connections in the database. Connections that match are marked as safelisted and hidden from the Dashboard's default view.

Safelist entries are global and are applied to all databases.

Entry Types¶

AC-Hunter supports six types of safelist entries:

IP¶

Safelist an individual IP address or CIDR block. You can apply it to connections where the IP appears as the source, destination, or both.

IPv4 and IPv6 are supported
CIDR notation is supported (e.g., 10.0.0.0/24, 2001:db8::/32)
Port numbers are not included in IP safelist matching

Example use case: Safelist a known DNS resolver like 8.8.8.8 as a destination.

FQDN¶

Safelist a fully qualified domain name. FQDNs are matched against destination connections only.

Exact match: update.microsoft.com
Wildcard match: *.microsoft.com matches any subdomain (e.g., update.microsoft.com, login.microsoft.com)

Example use case: Safelist *.googleapis.com to suppress all Google API traffic.

Pair (Source + Destination IP)¶

Safelist a specific source-to-destination IP connection. Both can be individual IPs or CIDR blocks.

Example use case: Safelist traffic from your monitoring server (10.1.1.50) to a specific external API endpoint.

FQDN Pair (Source IP + Destination FQDN)¶

Safelist connections from a specific source IP (or /24 CIDR) to a specific destination FQDN. Supports wildcard FQDNs.

Example use case: Safelist your update server's connections to *.ubuntu.com without safelisting all traffic to Ubuntu domains from every host.

ASN¶

Safelist all connections to or from an Autonomous System Number. Can be applied to source, destination, or both.

Example use case: Safelist a CDN provider's ASN to suppress all connections to their infrastructure.

Organization¶

Safelist all connections to or from a named organization (based on IP-to-ASN mapping). Can be applied to source, destination, or both.

Example use case: Safelist "Akamai Technologies" to suppress all traffic to Akamai-owned IP ranges.

Entry Type Summary¶

Type	Direction	Wildcard Support	Notes
IP	Source, Destination, or Both	No	Supports CIDR
FQDN	Destination only	Yes (`*.example.com`)	Ports stripped before matching
Pair	Source + Destination	No	CIDR pairs restricted to /24 or /120
FQDN Pair	Source IP + Destination FQDN	FQDN only	Source limited to /24 CIDR
ASN	Source, Destination, or Both	No	Valid range: 1–65534, 131072–4294967294
Organization	Source, Destination, or Both	No	Matched via IP-to-ASN lookup

Safelisting from the Dashboard¶

The fastest way to safelist a connection is directly from the Dashboard:

Find the connection you want to safelist in the results table
Click the Actions menu (kebab icon) on the row and select Safelist
The safelist dialog opens with tabs for the available entry types based on the connection's data:
- FQDN: if the connection has a destination domain name
- Destination: for the destination IP, ASN, or organization
- Source: for the source IP
- Pair: for the source-to-destination IP combination
Select the tab for the type of entry you want to create
Choose the direction (source, destination, or either) where applicable
Add an optional comment describing why this traffic is safe
Click Safelist

The entry is added to the global safelist and applied to the database you are currently viewing. The connection will disappear from the default Dashboard view.

Managing Safelists in Settings¶

For bulk operations and full safelist management, navigate to Settings → Safelist.

Viewing Entries¶

The safelist table shows all global entries with their name, type, scope, comment and impact (the number of connections the entry is hiding). Entries marked as Default were included with AC-Hunter's built-in safelist.

Editing Entries¶

Click an entry to edit its comment or modify its scope. When you change an entry's scope (e.g., switching from destination-only to both directions), AC-Hunter removes the old entry and creates an updated one, re-applying it to the relevant databases.

Removing Entries¶

Click the Delete button on any entry to remove it. The entry is removed from the global safelist and all connections it previously safelisted will become visible on the Dashboard again.

Clearing Safelists¶

Two bulk removal options are available:

Clear All: Removes every safelist entry (both user-created and default)
Clear Default: Removes only the built-in default entries, preserving your custom entries

Warning

Clearing safelists is irreversible. Export your safelist first if you may need to restore it.

Importing and Exporting¶

Export¶

From Settings → Safelist, click Export to download your entire safelist as a JSON file (safelist.json). Use this for:

Backing up your safelist before making changes
Transferring your safelist to another AC-Hunter instance
Keeping a version-controlled copy of your safelist

Import¶

From Settings → Safelist, click Import and select a safelist JSON file. AC-Hunter validates each entry and imports all valid ones. Any entries that fail validation are skipped and reported.

Imported entries are applied to all databases in the background.

Default Safelist¶

AC-Hunter ships with a built-in default safelist that covers common benign traffic patterns, including connections to well-known services like Microsoft, Apple, and Google infrastructure. Default entries are:

Marked with a Default flag in the safelist table
Automatically imported on first startup
Can be cleared separately from user-created entries using Clear Default

If the default safelist is updated in a new AC-Hunter release, the updated entries are automatically imported.

Viewing Safelisted Connections¶

To review what has been safelisted, use the filter toggle on the Dashboard:

Click the Filter button in the filter bar
Check the Safelisted Connections checkbox
The table now displays all connections, including safelisted ones

This is useful for auditing your safelist and verifying that important traffic is not being hidden.

Upgrading Safelists from AC-Hunter v6¶

If you are migrating from AC-Hunter v6, your existing safelist must be converted to the v7 format before it can be imported.

Step 1: Export from v6¶

In your AC-Hunter v6 instance, navigate to Settings → Safelist and export the safelist.

Step 2: Convert the file¶

Upload the exported JSON file to your v7 server and run the conversion tool:

hunt upgrade-prev7-safelist /path/to/v6-safelist.json /path/to/v7-safelist.json

The tool converts v6 entry types to their v7 equivalents:

v6 Type	v7 Type
`ip`, `cidr`, `ranges`	IP
`asn`	ASN
`asn_org`	Organization
`domain_literal`, `domain_pattern`	FQDN
`domain_pair_literal`, `domain_pair_pattern`	FQDN Pair
`pair`, `pair_cidr`	Pair
`useragent`	Skipped (no longer supported)

The tool reports any entries that could not be converted.

Step 3: Import into v7¶

In your AC-Hunter v7 instance, navigate to Settings → Safelist, click Import, and select the converted file.

Tips for Effective Safelisting¶

Start with the defaults. The built-in safelist covers common benign traffic. Review it before adding your own entries.
Be specific. Prefer FQDN Pair or Pair entries over broad IP or ASN entries when possible. Overly broad safelisting can hide real threats.
Use comments. Document why each entry was added so other analysts understand the reasoning.
Review periodically. Traffic patterns change. An entry that made sense six months ago may no longer be appropriate.
Use the safelisted view. Periodically toggle safelisted connections on the Dashboard to verify nothing important is being hidden.
Export before clearing. Always export your safelist before using Clear All, in case you need to restore entries.