DNSFilter

Overview

DNSFilter is a DNS-layer security and content-filtering service ("protective DNS"). It resolves DNS for your networks and devices, blocks requests to malicious or policy-violating domains before a connection is made, and records every lookup for reporting.

Bumblebee connects through DNSFilter's REST API and can retrieve your organization roster (for an MSP, every managed client), the networks and filtering policies protecting them, the Roaming Client agents installed on devices, and traffic reports — raw DNS query logs plus aggregated top-domain, top-category, and threats-over-time rollups.

The integration is read-only. Bumblebee can report on your DNSFilter configuration and traffic but cannot create or modify policies, networks, or agents.

How the account is structured

Knowing DNSFilter's object model makes the tools easier to ask for:

• Organization — the tenant. An MSP account is itself an organization; each managed client is a sub-organization beneath it.
• Network — an IP-based deployment site (an office's public IP range), filtered by the policy attached to it.
• User Agent — a Roaming Client install on an individual device, so filtering follows the device off-network.
• Policy — the filtering ruleset: blocked content categories, allow/blocklisted domains, safe-search enforcement.
• Category — DNSFilter's content taxonomy. Policies and reports reference categories by numeric ID; the category tool is the lookup table.

Prerequisites & Setup

You generate the API key yourself from the DNSFilter dashboard.

1. Sign in to the DNSFilter dashboard.
2. At the bottom of the left navigation, click Account, then Account Settings.
3. Open the Security tab.
4. Scroll to the API Keys panel and click + Create Key.
5. Give the key a name (e.g. BumblebeeIntegration), choose an Expiration (default 1 year), and click Generate Key.
6. Copy the key with the copy button — it is shown once and cannot be retrieved after you dismiss the dialog.

Two things worth noting:

• The key inherits the permissions of the user who created it. For MSP-wide reporting, create it as a user who can see every organization you want Bumblebee to cover.
• DNSFilter allows a maximum of 5 keys per account, and every key expires. When it does, calls start failing with Not Authorized and you'll need to generate a replacement.

Configure in Bumblebee

1. Go to the Integrations page in Bumblebee
2. Select DNSFilter
3. Paste your API Key
4. Save the configuration
5. Run a test request (e.g. list organizations) from the validation card

Available Tools

All tools are read-only.

Configuration & inventory

• list_organizations — The organizations this key can see. For an MSP, your managed-client roster. Returns id, name, cancellation state, MSP linkage, license and seat count. Optional: page, page_size.
• list_networks — IP-based deployment sites with the policy each is bound to, IP count and address. Optional: page, page_size.
• list_policies — Filtering policies with their blocked category IDs, explicit allow/blocklisted domains, safe-search settings, and attached networks. Optional: page, page_size.
• get_policy — One policy in full, including every attached network, subnet, MAC address, agent and collection. Required: policy_id.
• list_categories — The content-category dictionary (ID → name). Categories flagged security: true are threat categories (malware, phishing, botnets) rather than content categories. Optional: page, page_size.
• list_user_agents — Roaming Client installs with hostname, OS, agent version, state and last check-in time. Optional: page, page_size.

Traffic reports

Every report tool accepts the same time window — from_datetime / to_datetime in UTC YYYY-MM-DDThh:mm:ss, defaulting to the last 24 hours — plus organization_ids, network_ids and source (all, networks, agents, proxies) for scoping.

• list_query_logs — The raw per-lookup audit trail: which client asked for which FQDN, when, and whether it was allowed or blocked. Also filterable by domain (prefix), fqdn (substring), result (all/allowed/blocked), category_ids and security_report. Use this to investigate a specific device or domain.
• get_top_domains_report — Most-requested domains ranked by volume. Set type to blocked for the most-blocked domains, or security_report to true to rank threats only.
• get_top_categories_report — Most-requested content categories, already resolved to names.
• get_total_threats_report — Threat counts bucketed into a time series (bucket_size: auto, 15min, 1day), with per-source breakdowns.

Each tool accepts an optional response_filter (a JMESPath projection) with a sensible default; pass response_filter="@" to retrieve the full response envelope.

Example questions

• "List our DNSFilter organizations and the networks under them."
• "What were the most-blocked domains last week?"
• "Show the threat trend for the past 30 days, bucketed daily."
• "Which content categories are we blocking most?"
• "What does our filtering policy block, and which of those are security categories?"
• "Has anyone on the Boston network looked up anything flagged as malware in the last 24 hours?"
• "Which Roaming Clients haven't checked in recently?"

Notes

• Read-only. Bumblebee reports on DNSFilter but never changes policies, networks or agents.
• Reports default to the last 24 hours. Ask for an explicit window ("last 30 days") when you want more. An unparseable date is silently replaced by DNSFilter with that default rather than rejected.
• Reports default to your own organization. For MSP-wide questions, name the organizations you want, or ask Bumblebee to list them first.
• Categories are numeric in policies. Policies store blocked categories as IDs; Bumblebee resolves them via the category dictionary. Top-category reports come back already named.
• Rate limits. All DNSFilter endpoints are rate limited; heavy raw query-log paging is the most likely way to hit them. Prefer the aggregate reports for "top N" questions.