DNSAFE MSP Portal Docs

Platform Overview

DNSAFE is a DNS-layer security platform built for Managed Service Providers. You deploy our resolvers as the upstream DNS for your clients' networks, and all queries flow through our filtering engine before being answered. Threats, malware, phishing, and custom-blocked domains are intercepted at the DNS level — before a connection is ever made.

The platform has two portals and a REST API:

Key Concepts

• Partner — An MSP or reseller account. Partners own tenants and are billed per-tenant on a monthly plan.
• Tenant — A client network protected by DNSAFE. Each tenant has its own block/allow rules, IP mappings, and query logs.
• IP Mapping — Associates a client IP or CIDR range with a tenant so the resolver knows which policy to apply.
• IP Group — A named collection of IPs within a tenant that can have their own separate ruleset (e.g. a school's student lab vs. staff network).
• ThreatGrid — DNSAFE's threat intelligence blocklist, aggregated from Hagezi Pro, URLhaus, and other feeds. Applied platform-wide.

Architecture

When a device on a protected network makes a DNS query, the request flows through the following pipeline:

Rule flat files are regenerated every 5 minutes by sync_tenant_rules.py and reloaded by the Lua engine automatically. Changes you make in the portal take effect within ~5 minutes without any resolver restart.

Infrastructure

Quickstart Checklist

Follow these steps to get a client network protected from scratch. Each step links to the relevant section.

1. 1
   Create a Partner accountLog in to portal.dnsafe.net → Infrastructure → Partners → + Add Partner. Set the plan, contact email, and optional white-label branding.
2. 2
   Add a TenantInfrastructure → Tenants → + Add Tenant. Assign the tenant to the partner you just created.
3. 3
   Map the client's IP addressesOpen the tenant → IPs tab → add the client's public IP or CIDR range. This tells the resolver which policy to apply to that network.
4. 4
   Point the client's DNS to DNSAFEConfigure the client's router or firewall to use 3.12.124.91 as their upstream DNS. For encrypted DNS, use DoH or DoT (see DNS Setup).
5. 5
   Verify queries are flowingSecurity → Query Logs — filter by the tenant. Within a minute of the client making any DNS request you should see activity appear.
6. 6
   Configure filtering rulesOpen the tenant → Rules tab. Add domain block and allow rules as needed, or set up scheduled rules for time-based access control.
7. 7
   Enable add-on packs(Optional) Open the tenant → Add-ons tab to enable extended filtering categories like adult content, social media, or ads & trackers.

Partner Accounts

Partners are the top-level entities in the DNSAFE hierarchy. Each partner represents an MSP, reseller, or distribution channel. Partners own tenants and are billed on a monthly plan based on the number of active tenants.

Plans

Creating a Partner

Navigate to Infrastructure → Partners → + Add Partner. Fill in:

• Name — The partner's business name (shown in the portal and on invoices)
• Email — Primary contact and billing email
• Plan — Starter, Growth, or Enterprise

Once created, the partner receives a unique API key scoped to their account. They can manage their own tenants via the partner-level portal login.

Onboarding Progress

Each partner card shows a 5-step onboarding checklist. This tracks whether the partner has completed: account creation, first tenant added, client IP mapped, first query logged, and first custom rule configured. Use this to identify partners who haven't fully activated.

Partner API Keys

Each partner gets a unique API key generated on creation. This key is shown (masked) on the partner card. Partners use this key to authenticate REST API calls scoped to their account. Keys can be rotated from the partner detail page → API Key section.

Tenant Management

A tenant represents a single client network. Each tenant has isolated rules, IP mappings, and query logs. Multiple tenants can belong to the same partner.

Creating a Tenant

Go to Infrastructure → Tenants → + Add Tenant. You'll need to select the partner this tenant belongs to and give the tenant a name (typically the client's company name).

Tenant Detail View

Clicking a tenant opens the detail view with tabs:

Disabling a Tenant

Disabling a tenant stops DNS filtering for that network — queries will no longer be matched against the tenant's rules or the ThreatGrid blocklist. The tenant's IPs remain mapped but are inactive. Use this for temporary offboarding or billing holds rather than deleting the tenant.

IP Mapping

IP mapping is how the DNS resolver identifies which tenant a query belongs to. When a DNS query arrives, the Lua policy engine looks up the client IP in the tenant IP table. If a match is found, that tenant's rules are applied. If no match is found, the query passes through the global ThreatGrid blocklist only.

Adding IP Addresses

Open a tenant → IPs tab → + Add IP. You can enter:

• Single IPv4 — e.g. 203.0.113.42
• IPv4 CIDR range — e.g. 203.0.113.0/24
• Single IPv6 — e.g. 2001:db8::1

IP Conflicts

The same IP cannot be mapped to two different tenants simultaneously. If you attempt to add an IP that's already assigned to another tenant, you'll receive a conflict error. You must remove it from the existing tenant first.

Dynamic IPs

For clients with dynamic IPs (residential or small business connections), you have two options:

• Use a CIDR range that covers the ISP's IP pool for that client
• Use the DoH/DoT endpoint with per-tenant credentials (see DoH / DoT) — this identifies the tenant by auth token rather than IP

Propagation Time

IP mappings are synced to the resolver's flat files every 5 minutes via sync_tenant_rules.py. New mappings take effect within 5 minutes. The IP-to-tenant Redis cache is updated in real time on save.

IP Groups

IP Groups let you apply different filtering policies to different segments of the same tenant's network. For example, a school might have one group for student devices (strict filtering) and another for staff (relaxed filtering).

Creating a Group

Tenant detail → Groups tab → + New Group. Give it a name, then add the IPs or CIDR ranges that belong to it. These IPs must already be mapped to the parent tenant.

Group Rule Priority

When an IP belongs to a group, the resolver applies rules in this order:

1. Group allow rules (highest priority — explicitly allowed)
2. Group block rules
3. Group scheduled rules
4. Tenant allow rules
5. Tenant block rules
6. Tenant scheduled rules
7. Global ThreatGrid blocklist (lowest priority)

DNS Resolver Setup

Configure your clients to use the following resolver addresses. The client's router, firewall, or DHCP server should hand out these addresses as the upstream DNS.

Standard DNS (UDP/TCP port 53)

Per-Platform Configuration

DNS-over-HTTPS (DoH) & DNS-over-TLS (DoT)

DNSAFE supports encrypted DNS protocols for clients that need privacy or where standard port 53 is blocked.

Encrypted DNS queries are still matched to tenants via the client IP. For clients with dynamic IPs, contact support for per-tenant token-based DoH authentication.

Browser DoH Configuration

PowerDNS & Lua Policy Engine

DNSAFE's resolver is built on PowerDNS Recursor with a custom Lua policy script. The Lua engine runs synchronously on every incoming DNS query and decides in microseconds whether to block, allow, or forward the request.

How Blocking Works

When a domain is blocked, the resolver returns NXDOMAIN (domain does not exist). For web traffic, the browser then cannot load the site. The client is redirected to the DNSAFE block page hosted at the resolver's IP, which displays a branded "This site has been blocked" message.

Flat File Structure

The Lua engine reads pre-compiled flat files from disk rather than querying PostgreSQL on every request. This gives sub-millisecond policy evaluation at high query volumes.

Files are regenerated by sync_tenant_rules.py (cron every 5 minutes). The Lua engine detects file changes automatically.

Block & Allow Rules

Custom rules let you extend or override the default ThreatGrid filtering for individual tenants. Rules apply to the entire tenant unless scoped to an IP group.

Adding a Rule

Tenant detail → Rules tab → + Add Rule. Enter the domain and select Block or Allow.

• Block — Returns NXDOMAIN for this domain for all IPs in the tenant.
• Allow — Explicitly passes this domain even if it appears in the ThreatGrid blocklist. Useful for whitelisting a legitimate site that's been incorrectly flagged.

Domain Format

Enter bare domains without http:// or paths:

• ✅ tiktok.com — blocks the domain and all subdomains
• ✅ ads.example.com — blocks only this subdomain
• ❌ https://tiktok.com/feed — paths are stripped automatically

Bulk Rule Import

For large rule sets, use the REST API. POST /api/tenant/{id}/rules accepts a JSON array of domain/action pairs and is significantly faster than adding rules one at a time through the UI.

Scheduled Rules

Scheduled rules allow you to block or allow a domain only during specific time windows on specific days of the week. This is useful for scenarios like blocking social media during school hours or allowing gaming sites only on weekends.

Creating a Scheduled Rule

Tenant detail → Rules tab → + Add Rule → Scheduled. Configure:

• Domain — The domain to block or allow
• Action — Block or Allow
• Days — Select which days the rule is active (e.g. Mon–Fri)
• Time window — Start and end time in the tenant's local timezone

How It Works

Scheduled rules are stored in .sched files in pipe-delimited format:

domain|action|days_bitmask|start_minute|end_minute

The Lua engine reads the current time on every query and checks if the query falls within the rule's active window. Days are encoded as a bitmask (Mon=1, Tue=2, Wed=4, Thu=8, Fri=16, Sat=32, Sun=64). Time is expressed in minutes since midnight.

Time Zone

Scheduled rules run in the server's timezone (UTC by default). When configuring time windows through the portal, times are entered and displayed in the browser's local timezone and converted automatically.

Group Rules

Group rules work identically to tenant-level rules but apply only to IPs that are members of a specific IP group. This lets you have different policies for different departments, floors, or device categories within the same tenant network.

Example Use Cases

• K-12 school: Student group blocks social media and gaming; staff group allows them
• Office: Guest Wi-Fi group applies strict filtering; employee group is more relaxed
• Retail: POS terminal group blocks everything except payment processor domains

Manage group rules from: Tenant detail → Groups tab → open a group → Rules.

ThreatGrid Blocklist

ThreatGrid is DNSAFE's aggregated threat intelligence blocklist. It's applied to every DNS query across the entire platform — for all tenants — regardless of their custom rules.

Feed Sources

The combined blocklist contains approximately 395,000+ domains and is refreshed automatically. The last update timestamp and source breakdown are shown on the dashboard.

Override with Allow Rules

If a domain is in the ThreatGrid blocklist but you need to allow it for a specific tenant (e.g. a legitimate internal tool that was incorrectly flagged), add an Allow rule for that domain on the tenant. Tenant allow rules take priority over the global blocklist.

Dashboard Feed Status

The dashboard Overview page shows the ThreatGrid Feed card including last update time, sources, and refresh interval. If the feed hasn't updated in over 30 minutes, check the update_feeds.py cron on the server.

Add-on Packs

Add-on packs let you enable additional filtering categories per tenant, beyond the default ThreatGrid blocklist. Each pack is billed per-tenant per-month via Stripe metered billing.

Enable or disable packs from: Tenant detail → Add-ons tab. Changes apply at the next 5-minute sync cycle.

Query Logs

Every DNS query processed by DNSAFE is logged with full context. Logs are accessible in real time from the portal and via the REST API.

Accessing Logs

Two entry points:

• Security → Query Logs — All queries across all tenants, with tenant and partner filters
• Tenant detail → Logs tab — Scoped to a single tenant

Filters

Log Fields

Live Mode

Toggle Live in the top-right of the Query Logs page to enable automatic refresh every 5 seconds. Useful for watching queries in real time during a client setup or troubleshooting session.

Export

Click Export CSV to download the current filtered log set. The export includes all columns and respects active filters. For large exports or automated reporting, use the REST API GET /api/logs endpoint.

Tenant Health

The Tenant Health page (Operations → Tenant Health) gives a real-time view of every tenant's activity status. It auto-refreshes every 30 seconds.

Status Definitions

Alerts

DNSAFE sends email alerts when a tenant goes offline or experiences a threat spike. Configure alert thresholds and recipients in Settings → Notifications. Alerts include a 1-hour cooldown to prevent flooding.

Domain Intelligence

The Domain Intelligence scanner (Security → Domain Intel) lets you run a comprehensive threat analysis on any domain. It's useful for investigating suspicious queries in your logs or vetting a domain before adding a rule.

What It Checks

• DNS records — A, AAAA, MX, NS, TXT, CNAME
• RDAP registration — Registrar, creation date, expiry, registrant org
• Geo-IP — Country, ASN, hosting provider for each resolved IP
• ThreatGrid match — Whether the domain is in the current blocklist
• Query history — How often this domain has been queried on your network and with what actions
• Risk score — 0–100 composite score based on domain age, geo, flags, and threat feed matches

Risk Score Bands

Scans are rate-limited to 50 per day on Starter/Growth plans. Enterprise plans have unlimited scans.

Alerts & Notifications

Configure automated alerts in Settings → Notifications. Alerts are sent via email to the address on your account.

API Keys

DNSAFE provides a REST API for programmatic access to query logs, rule management, tenant data, and more. API keys are managed from Operations → API Keys.

API Key Tiers

Authentication

Pass your API key in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Base URL

https://api.dnsafe.net

Key Endpoints

For the full API reference with request/response schemas, see docs.dnsafe.net.

Plans & Billing

DNSAFE billing is managed through Stripe. Partners are billed monthly based on their plan and active tenant count. Add-on packs are billed as metered usage per tenant per month.

Billing Cycle

Usage is reported to Stripe daily at midnight UTC by the usage_reporter.py script. Invoices are generated at the end of each billing period. You can download invoices and update your payment method from Settings → Billing or via the Stripe billing portal link.

Overage

If your tenant count exceeds your plan's limit, the portal will notify you. Additional tenants cannot be added until you upgrade. Contact support to discuss a custom Enterprise arrangement if your Growth plan limit is insufficient.

Trialing

New partners enter a trial period. During the trial, all features are available with no charge. The partner card in the portal shows the number of trial days remaining. Once the trial expires, a valid payment method is required to continue.

White-Label Branding

Enterprise partners can apply their own branding to the MSP portal and the DNS block page shown to end users. White-label is available on Enterprise plans.

Configuring Branding

Partner detail → expand White-Label Branding section. You can configure:

• Company name — Shown in the portal header and emails
• Support email — Shown on the block page and in alert emails
• Primary color — Accent color applied throughout the portal (hex)
• Logo URL — Your logo hosted on a CDN, shown in the portal header
• Custom domain — Serve the portal from your own domain (e.g. protect.yourmsp.com)

Block Page Branding

When a white-label configuration is set, the block page shown to end users on the client's network displays the partner's company name and support email instead of DNSAFE's. The block page URL and styling remain the same.

MFA & Duo Setup

DNSAFE supports Duo Security for multi-factor authentication on the MSP portal. MFA can be required for individual partners or enforced platform-wide for all admin logins.

Enabling Duo for a Partner

Partner detail → Security tab → Duo MFA → Enable. Enter the partner's Duo application credentials:

• Integration Key (DXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)
• Secret Key
• API Hostname (e.g. api-xxxxxx.duosecurity.com)

Once enabled, users logging in under that partner will be redirected to Duo for a second factor after entering their password.

Platform-Wide MFA

Admin Settings (gear icon, admin only) → Security tab → toggle Require MFA for all admin logins. This enforces Duo for all users regardless of partner-level settings.

Consumer Accounts

The consumer portal (my.dnsafe.net) is a self-service portal for home and personal users. Consumer accounts are separate from partner/tenant accounts and are managed independently.

As an admin you can view all consumer accounts from Infrastructure → Consumers. This shows plan, device count, subscription status, and join date.

Consumer Plans

Suspending a Consumer

From the Consumers list, click Suspend on a consumer row to immediately disable their account. Their device IPs are removed from the consumer IP map and queries will no longer be filtered. Use this for billing issues or ToS violations.

Consumer Rules

Consumer accounts can manage their own block and allow rules from the consumer portal (my.dnsafe.net/rules). These rules apply to all registered devices on their account.

Consumer rules are stored separately from tenant rules and are evaluated by the Lua engine using the consumer IP map at /var/lib/dnsafe/consumer_ips.txt. They are synced every 5 minutes by the same sync_tenant_rules.py script.

As an admin you can view a specific consumer's rules from their detail page (Infrastructure → Consumers → open consumer → Rules tab).

Troubleshooting

Queries not appearing in logs

1. Confirm the client's DNS is actually pointing to 3.12.124.91 — run nslookup dnsafe.net from the client and check the server shown
2. Check that the client's egress IP is mapped to a tenant (Infrastructure → Tenants → the tenant → IPs tab)
3. Check that the tenant is active (not disabled)
4. Wait up to 5 minutes for the IP map sync cycle

A domain isn't being blocked

1. Verify the rule exists on the correct tenant (not a different one)
2. Check the domain format — enter just the domain, no http:// prefix
3. Wait for the 5-minute sync cycle
4. Try flushing the client's DNS cache: ipconfig /flushdns (Windows) or sudo dscacheutil -flushcache (macOS)
5. Use Domain Intelligence to confirm the domain isn't appearing as allowed somewhere in the rule chain

A blocked domain is showing up as allowed

Check the rule priority chain: group allow rules override tenant blocks. If the querying IP is in a group that has an allow rule for the domain, the block won't fire. Check the group's allow list first.

The block page isn't showing

The block page relies on the browser making an HTTP request to the resolver's IP after receiving NXDOMAIN. Some browsers cache previous DNS answers for longer. Try a hard refresh or open an incognito window. Also check that the client's router doesn't have DNS rebind protection blocking the response.

API returning 401 Unauthorized

Your API key may have been rotated or the Authorization header format is incorrect. Ensure you're passing: Authorization: Bearer YOUR_KEY (note the space after Bearer).

ThreatGrid feed not updating

Check the dashboard — the ThreatGrid Feed card shows the last update time. If it hasn't updated in over 30 minutes, check the cron on the server:

sudo journalctl -u dnsafe-threatgrid -n 50 --no-pager

Frequently Asked Questions

Can a client IP be mapped to multiple tenants?

No. Each IP can only belong to one tenant at a time. If you need different policies for different subnets, use CIDR ranges that don't overlap, with each range mapped to its own tenant.

How quickly do rule changes take effect?

Rule changes are written to the database immediately. The flat files used by the Lua engine are regenerated every 5 minutes. DNS resolvers also cache responses — clients may need to flush their DNS cache for the change to take immediate effect.

Does DNSAFE log the full DNS query including all subdomains?

Yes. Every query is logged with the exact domain queried (including any subdomain), the resolved action, client IP, and timestamp.

What happens if the DNSAFE resolver is unreachable?

If the resolver is unreachable, DNS queries will fail and clients will experience internet outages (DNS is required for nearly all internet traffic). Configure a secondary DNS — either a second DNSAFE resolver IP if available on your plan, or a fallback like your ISP's DNS as a secondary only. Note that a secondary DNS will bypass DNSAFE filtering.

Can I use DNSAFE alongside an existing firewall DNS policy?

Yes. DNSAFE operates at the DNS layer and is complementary to firewall rules. DNS filtering is faster (blocks at query time before any connection) and easier to manage for domain-based policies. Use your firewall for IP/port-level controls and DNSAFE for domain-level filtering.

Are query logs retained indefinitely?

Log retention depends on your plan. Contact support for your plan's specific retention policy. For compliance requirements, use the REST API to export logs to your own storage on a scheduled basis.

Can partners log in to the MSP portal directly?

Yes. Partners use the same portal.dnsafe.net login. The portal automatically scopes their view to their own tenants — they cannot see other partners' tenants or admin-level settings.