How do I install BlackVeil DNS & Email Security Scanner?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does BlackVeil DNS & Email Security Scanner need an API key?

No required environment variable is listed on this record.

What transport does BlackVeil DNS & Email Security Scanner use?

BlackVeil DNS & Email Security Scanner is reached over HTTP.

When was BlackVeil DNS & Email Security Scanner last checked?

Last checked 2026-10-22. DNS and email security scanner with 81 MCP tools for SPF, DMARC, DNSSEC, SSL, and brand audits.

BlackVeil DNS & Email Security Scanner MCP server

Tool	What it does
check_mx	Look up MX records for a domain. Identifies which mail servers receive inbound email for the domain and which email hosting provider is used (Google Workspace, Microsoft 365, Proofpoint, etc.). Use when asked which email provider hosts inbound mail for a domain, or to see MX record configuration. Pa
check_spf	Look up and validate the SPF record for a domain. Lists all IP addresses and third-party senders authorised to send email on behalf of the domain, flags syntax errors, and shows the trust surface (which mail servers are whitelisted). Use when you need to know who is permitted to send email as a doma
check_dmarc	Look up and validate the DMARC record for a domain. Shows the enforcement level (none/quarantine/reject), alignment mode (strict/relaxed), and aggregate/forensic reporting destinations. Use to determine a domain's DMARC enforcement level, whether it sends aggregate reports, or if it is protected aga
check_dkim	Look up DKIM records for a domain. Probes common selectors, validates the signing algorithm used for outgoing email (RSA-1024/2048, Ed25519), and reports key strength. Use to verify that outbound email signatures are cryptographically sound. Part of the scan_domain audit.
check_dnssec	Check DNSSEC status for a domain. Verifies whether DNS is tamper-proof and protected against cache poisoning and DNS spoofing attacks by validating DNSKEY and DS records. Reports whether DNSSEC is enabled and validating. Part of the scan_domain audit.
check_ssl	Check the HTTPS/TLS posture of a domain: HTTPS reachability, HSTS policy, and HTTP-to-HTTPS redirect. Also returns certificate metadata (issuer, expiry date, days remaining, SAN count) read from public Certificate Transparency logs — this describes the most recently LOGGED certificate, which may dif
check_mta_sts	Check whether a domain enforces SMTP TLS for inbound mail via MTA-STS, protecting against downgrade attacks. Queries _mta-sts.<domain> and fetches the policy file, reports mode (enforce/testing/none) and MX coverage. Use to verify whether inbound SMTP is protected against TLS downgrade or MITM — dis
check_ns	Audit a domain’s nameserver delegation and redundancy. Identifies the DNS hosting provider and, when the infrastructure probe is available, directly compares parent and child NS sets, verifies authoritative AA responses, and checks required glue addresses. Use to detect stale registrar delegations,
check_caa	Look up CAA records for a domain. Shows which Certificate Authorities are authorized to issue certificates. Part of the scan_domain audit.
check_bimi	Check the BIMI brand-logo record at default._bimi.<domain>. Validates the logo URL (l=) and the presence of mark-certificate authority evidence (a=) — the a= tag is a bare URL, so the certificate type (VMC or CMC) is not determined — and verifies the DMARC enforcement prerequisite (p=quarantine/reje
check_tlsrpt	Check whether a domain has SMTP TLS Reporting (TLS-RPT) configured. Queries _smtp._tls.<domain> for the v=TLSRPTv1 record and validates its reporting destination (rua= mailto:/https:), flagging a missing record, duplicate records, or an invalid/absent reporting URI. Complements MTA-STS by giving vis
check_http_security	Audit a domain's browser-facing HTTP security headers over HTTPS. Inspects Content-Security-Policy (flagging unsafe-inline/unsafe-eval/wildcards), X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and the cross-origin isolation headers (COOP/COEP/CORP), and detects CDN/WA
check_dane	Check DANE/TLSA certificate pinning for SMTP at port 25. Resolves the domain's MX hosts and looks up TLSA records at _25._tcp.<mx-host>, validating their syntax, usage/selector/matching-type fields and DNSSEC backing on the MX host's zone. The record is reported as present but UNVERIFIED: there is n
check_ptr	Verify forward-confirmed reverse DNS (PTR/FCrDNS) for mail servers. Part of the scan_domain audit.
check_dane_https	Verify DANE certificate pinning for HTTPS connections. Looks up TLSA records at _443._tcp.{domain} (port 443) and validates their syntax, usage/selector/matching-type fields and DNSSEC backing. The record is reported as present but UNVERIFIED in every deployment: comparison against the certificate t
check_svcb_https	Validate HTTPS/SVCB records (RFC 9460) for modern transport capability advertisement. Part of the scan_domain audit.
check_lookalikes	Detect active typosquat and lookalike/homoglyph domains that impersonate your brand and could be used in phishing. Identifies character-substitution and visual-confusion domains registered by attackers. Distinct from check_shadow_domains (TLD variants with auth gaps) and discover_brand_domains (legi
check_subdomailing	Detect SubdoMailing risk: analyzes the SPF include chain for dangling or hijackable subdomains that could let an attacker send email as the domain. Use when you want to know if an SPF include chain can be hijacked through a dangling domain, or to detect subdomain mailing risk hidden in SPF includes.
scan_domain	Run a full DNS and email security audit for a single domain. Aggregates every scan-included check in parallel (SPF, DKIM, DMARC, DNSSEC, TLS/SSL, MTA-STS, CAA, BIMI, subdomain takeover, and more) and returns an overall security score, NIST-aligned letter grade (6-band A+/A/B/C/D/F), maturity stage,
batch_scan	Bulk-scan up to 10 domains in parallel. Runs a full security audit on each domain in the list and returns score, NIST-aligned letter grade (6-band A+/A/B/C/D/F), and finding counts per domain. Use when you want to audit multiple domains at once or do a bulk scan of several domains simultaneously — d
batch_scan_start	Start a durable asynchronous scan of 1–10 domains. Returns a stable job ID; replaying the same idempotency key with the same principal, normalized inputs, and scoring versions returns the same job.
batch_scan_status	Read the owner-scoped status of an asynchronous batch scan.
batch_scan_findings	Fetch owner-scoped findings for a completed asynchronous batch scan.
compare_domains	Side-by-side security comparison of 2–5 domains. Shows relative scores, category gaps, and unique weaknesses for each domain. Use when comparing your security posture against a competitor, or doing a head-to-head comparison between multiple domains.
compare_baseline	Compare a domain's current security configuration against a fixed policy baseline to determine compliance. Use to check whether a domain meets a policy requirement — not for tracking improvement/regression over time (use analyze_drift) and not for comparing multiple domains (use compare_domains).
check_shadow_domains	Find alternate TLD variants of a domain (e.g. example.net, example.co) that have weak or missing email authentication and could be used to spoof email. Use when asked about TLD variants with email auth gaps — distinct from check_lookalikes which detects typosquat/homoglyph impersonation domains.
check_txt_hygiene	Audit TXT records for stale entries and SaaS exposure.
check_mx_reputation	Check whether the mail server (MX) IP addresses are listed on spam blocklists (Spamhaus, Barracuda, SORBS, and other RBLs). Also verifies reverse DNS for MX hosts. Use when you want to know if your mail server IP is blacklisted, or if your MX is on any blocklist — distinct from check_rbl which check
check_srv	Map a domain's DNS-visible service footprint by probing 19 common SRV record prefixes (email, calendar, messaging, directory, web) in parallel. Returns discovered services and flags insecure service advertisements — e.g. plaintext IMAP/POP3/LDAP without an encrypted variant. A domain with no matches
check_zone_hygiene	Audit DNS zone hygiene: identifies sensitive or forgotten subdomains exposed in DNS, stale SOA records, and zone propagation issues. Use to find any sensitive subdomains that should not be publicly visible, or to audit overall DNS zone cleanliness.
generate	Generate a DNS/email security remediation artifact. Artifact types: spf_record (build a new SPF record), dmarc_record (create a DMARC policy), dkim_config (DKIM key setup), mta_sts_policy (generate an MTA-STS policy file), fix_plan (prioritized remediation plan for all findings), or rollout_plan (ph
get_domain_rank	Rank a domain against its country or global cohort using the GSI benchmark corpus. Accepts a domain score (from scan_domain) and optional country/sector; returns a percentile: "scores better than X% of peers". Owner-gate exempt — public cohort data only.
get_benchmark	Get industry benchmark data: shows what percentile a domain's security score ranks at within its sector or country cohort, the mean score, and the most common DNS security failures across the industry. Use when asked how a score compares to the industry average, what percentile a score is in, or wha
get_provider_insights	Get security benchmarks and common configuration issues for a specific email or DNS service-provider cohort (e.g. Google Workspace customers, Microsoft 365 customers). Use when asked how an email service provider compares to competitors on security posture, or to see typical misconfigurations for a
assess_spoofability	Compute a composite email spoofability risk score (0–100, higher = more spoofable) by combining SPF trust surface, DMARC enforcement, and DKIM coverage. Returns a risk level (minimal→critical), per-control sub-scores, and plain-language summary of how easy it would be to spoof email from the domain.
check_resolver_consistency	Check DNS consistency across 4 public resolvers.
explain_finding	Explain a finding with impact and remediation.
map_supply_chain	Map DNS-visible third-party service dependencies for a domain. Correlates SPF, NS, TXT verifications, SRV services, and CAA records to reveal which third-party vendors can send email as the domain, control DNS, or access integrated services. Use when asked to map third-party or supply-chain dependen
analyze_drift	Measure whether a domain's DNS security posture improved or regressed by comparing the current state against a prior scan snapshot. Returns a drift classification (improving/stable/regressing/mixed), score delta, and lists of improvements and regressions. Use to answer "did our security score improv
validate_fix	Re-check a specific security control after applying a fix, to confirm the finding is now resolved. Use only when a fix has already been applied and you want to verify or confirm the remediation was successful — not for initial inspection of a record.
resolve_spf_chain	Trace the full SPF include chain for a domain. Recursively resolves all includes, shows lookup count, tree depth, and flags circular includes or exceeding the 10-lookup limit.
discover_subdomains	Find subdomains of a domain using Certificate Transparency logs. Reveals shadow IT, forgotten services, and unauthorized certificate issuance. Returns a CT SAMPLE, not an asset inventory: the count is a lower bound, a host with no publicly-logged certificate never appears, and the result carries a p
map_compliance	Map scan findings to compliance frameworks: NIST 800-177, PCI DSS 4.0, SOC 2, CIS Controls. Shows pass/fail/partial status per control.
sge_quickscan	Answer, for ONE domain, whether it meets the New Zealand Secure Government Email (SGE) requirements agencies must satisfy by October 2026. Reports all seven SGE controls — DMARC p=reject, SPF -all, DKIM, SMTP transport TLS, MTA-STS enforce, TLS-RPT, full sub-domain coverage — each as satisfied, not
prioritize_portfolio_leads	Rank a brand’s portfolio (or an explicit domain set) into prioritized registrar-partner sales leads by product-gap value × severity. Multi-domain, paid. Reuses map_registrar_products per domain, then ranks. Distinct from map_registrar_products (per-domain product mapping) and batch_scan (raw scores)
simulate_attack_paths	Analyze current DNS posture and enumerate specific attack paths an adversary could exploit, with severity, feasibility, steps, and mitigations.
check_dbl	Check domain reputation against DNS-based Domain Block Lists (Spamhaus DBL, URIBL, SURBL). Returns listing status with decoded return codes.
check_rbl	Check MX server IP reputation against 6 DNS-based Real-time Blocklists (SpamCop, UCEProtect, Mailspike, Barracuda, PSBL). Resolves MX hosts to IPs first.
cymru_asn	Map domain IPs to Autonomous System Numbers via Team Cymru DNS. Returns ASN, prefix, country, registry, and organization for each IP. Flags high-risk hosting ASNs.
rdap_lookup	Fetch domain registration data via RDAP (modern WHOIS replacement). Returns the domain registrar (the company the domain was registered with), registrant contact, creation/expiration dates, EPP status codes, and domain age. Use when asked who registered the domain, who the registrar is, or when the
check_realtime_threat_feed	Check a domain against BlackVeil real-time threat intelligence (curated intel-gateway feed). Distinct from DNSBL checks. Operator-deploy only; degrades to info when unprovisioned.
check_nsec_walkability	Assess zone walkability risk by analyzing NSEC3PARAM configuration. Detects plain NSEC zones, weak NSEC3 parameters, and opt-out flags.
check_dnssec_chain	Walk the full DNSSEC chain of trust from the DNS root down to the target domain, tracing DS/DNSKEY records and algorithm usage at each zone level. Use when asked to trace the chain of trust from the DNS root, or to see the full DNSSEC delegation path step by step.
check_agent_discovery	Assess the security posture of IETF BANDAID agent-discovery records (draft-mozleywilliams-dnsop-dnsaid). Detects SVCB agent records under _agents/_index._{protocol}._agents, reports whether the discovery zone is DNSSEC-anchored (unsigned = spoofable agent endpoints), evaluates DANE/TLSA binding trus
check_llms_txt	Inspect a domain's published /llms.txt and /llms-full.txt for links and install instructions an AI agent could inherit from someone else. Parses and dedupes the links (same-origin vs external), sweeps external link hosts for dangling CNAMEs and deprovisioned-service fingerprints (evidence of a dangl
check_dnskey_strength	Audit the cryptographic strength of DNSKEY signing algorithms used for DNSSEC. Reports which algorithm is used for DNSSEC signing keys (RSA/SHA-1, RSA/SHA-256, ECDSA P-256, Ed25519, etc.), flags deprecated algorithms (RSA/SHA-1, DSA), independent of whether the DNSSEC chain validates. Use when asked
check_fast_flux	Detect fast-flux DNS behavior: performs multiple rounds of A/AAAA queries and checks whether IP addresses are rotating rapidly on each DNS query (a sign of botnet or malicious infrastructure). Compares IP answer sets and TTLs across rounds to identify rapidly rotating infrastructure used to hide mal
check_subdomain_takeover	Sweep subdomains for dangling CNAMEs pointing to deprovisioned cloud services that could be claimed by an attacker (subdomain takeover vulnerabilities). Detects 16 provider families (AWS S3/CloudFront, Azure Front Door/CDN/Blob/App Service, GCP Cloud Storage, Heroku, GitHub Pages, Vercel, Firebase,
check_authoritative_dns_infra	Measure authoritative DNS infrastructure posture for a hostname over direct DNS-over-TCP/53 from a single vantage: TCP/53 reachability, the authoritative AA flag, recursion exposure, SOA serial consistency across nameservers, DNSKEY/RRSIG presence (not validation), IPv4/IPv6 answer parity, and unsup
check_root_server_set	Query a rotating sample of 3 root servers per call and compare the priming NS set, glue, SOA serials, and cross-root consistency against the embedded official root hints. Uses BV_INFRA_PROBE when available; without it, returns the embedded hints as reference data only.

BLACKVEIL DNS

Know where you stand.

Source-available DNS & email security scanner for Claude, Cursor, VS Code, and MCP clients across Streamable HTTP, stdio, and legacy HTTP+SSE.

Try it in 30 seconds

Claude Desktop (one-click install):

Download the Blackveil DNS extension and open it — the current 81-tool surface is available instantly. Verify your download.

Claude Code (one command):

claude mcp add --transport http blackveil-dns https://dns-mcp.blackveilsecurity.com/mcp

Then ask: scan anthropic.com

Smithery (one command):

smithery mcp add MadaBurns/bv-mcp

Verify the endpoint is live:

curl https://dns-mcp.blackveilsecurity.com/health

No install. No API key. One URL for hosted HTTP:

Endpoint   https://dns-mcp.blackveilsecurity.com/mcp
Transport  Streamable HTTP · JSON-RPC 2.0
Auth       None required

Transport support:

Streamable HTTP: POST /mcp, GET /mcp, DELETE /mcp
Native stdio: blackveil-dns-mcp CLI from the blackveil-dns npm package
Legacy HTTP+SSE: GET /mcp/sse bootstrap stream plus POST /mcp/messages?sessionId=...

For Streamable HTTP, clients should retain the Mcp-Session-Id returned by initialize and send it on every subsequent request, including notifications. Send the negotiated version in MCP-Protocol-Version; unsupported values are rejected with HTTP 400, while expired or terminated sessions return 404 and require a fresh initialize.

What you get

81 MCP tools with 19 scoring categories — SPF, DMARC, DKIM, DNSSEC, SSL/TLS, MTA-STS, NS, CAA, MX, BIMI, TLS-RPT, subdomain takeover, HTTP security headers, DANE, SVCB/HTTPS, DANE-HTTPS, subdomailing, reverse DNS (PTR/FCrDNS), and DNSKEY strength
Maturity staging — Stage 0-4 classification (Unprotected to Hardened) with score-based capping to prevent inflated labels
Trust surface analysis — detects shared SaaS senders in SPF, both cataloged platforms (Google, M365, SendGrid) and uncataloged hosts identifiable by their spf delegation label, then cross-references DMARC enforcement to determine real exposure
Guided remediation — generate (artifact=fix_plan) produces provider-aware prioritized actions; its record artifacts (spf_record, dmarc_record, dkim_config, mta_sts_policy, rollout_plan) output ready-to-publish records; validate_fix confirms whether a fix was applied successfully
Supply chain mapping — map_supply_chain correlates DNS signals to build a full third-party dependency graph with trust levels and risk signals
Attack path simulation — simulate_attack_paths enumerates specific paths (spoofing, takeover, hijack) with severity, steps, and mitigations
Compliance mapping — map_compliance maps scan findings to NIST 800-177, PCI DSS 4.0, SOC 2, and CIS Controls
Self-tuning scoring — adaptive weights adjust category importance based on patterns seen across scans via Durable Object telemetry
Per-tier analytics — usage tracking by auth tier with operator API for tier summaries, key-level usage, and daily digests
Read-only — checks never modify a target and need no authorization from it. Most are passive lookups over public Cloudflare DNS-over-HTTPS; check_authoritative_dns_infra and check_root_server_set query authoritative and root nameservers directly over TCP/53, and for authenticated callers check_authoritative_dns_infra also tests whether a domain's nameservers refuse a zone transfer (no zone data is retrieved)

Tools

  81 MCP tools · 7 prompts · 6 resources

  Email Auth             Infrastructure          Brand & Threats       Meta
 ─────────────          ──────────────          ───────────────       ───────────────
  check_mx              check_dnssec            check_bimi            scan_domain
  check_spf             check_ssl               check_tlsrpt          batch_scan
  check_dmarc           check_ns                check_lookalikes      compare_domains
  check_dkim            check_caa               check_shadow_domains  compare_baseline
  check_mta_sts         check_http_security                           explain_finding
  check_subdomailing    check_dane
  check_mx_reputation   check_dane_https        DNS Hygiene           Remediation
                        check_svcb_https       ─────────────         ───────────────
                        check_ptr               check_txt_hygiene     generate (one tool;
  Intelligence          check_srv                                       artifact=fix_plan,
 ─────────────          check_zone_hygiene                              spf_record,
  get_benchmark         check_resolver_         Discovery               dmarc_record,
  get_domain_rank         consistency          ─────────────           dkim_config,
  get_provider_                                 discover_brand_         mta_sts_policy,
    insights            check_dbl                domains                rollout_plan)
  assess_spoofability   check_rbl               brand_audit_single    validate_fix
  map_supply_chain      cymru_asn               brand_audit_batch_
  analyze_drift         rdap_lookup               start
  resolve_spf_chain     check_nsec_             brand_audit_status
  discover_subdomains     walkability           brand_audit_get_
  map_compliance        check_dnssec_chain        report
  prioritize_portfolio_
    leads
  simulate_attack_paths check_fast_flux         list_brand_audit_watches
  check_agent_discovery check_dnskey_strength
  check_llms_txt        check_authoritative_dns_infra
                        check_root_server_set   register_brand_audit_watch
                                                delete_brand_audit_watch

  + check_subdomain_takeover (standalone tool + internal — runs inside scan_domain)
  + check_authoritative_dns_infra and check_root_server_set (authoritative DNS infrastructure profile)
  + batch_scan_start / batch_scan_status / batch_scan_findings
    (async start → poll → fetch sibling of batch_scan)
  + sge_quickscan (NZ Secure Government Email readiness for one domain)
  + discover_brand_domains_start / discover_brand_domains_status / discover_brand_domains_findings
    (async start → poll → fetch sibling of discover_brand_domains, for clients that time out on the ~24s sync call)

  Operator-deploy only (BV_RECON binding; degrade to unprovisioned on self-hosted BUSL deployments):
  + check_realtime_threat_feed   — curated intel-gateway threat feed lookup
  + scan_buckets_start           — async cloud-bucket discovery scan (start → poll → findings)
  + scan_buckets_status          — poll status of a running bucket scan
  + scan_buckets_findings        — retrieve findings for a completed bucket scan
  + osint_investigate_domain_start          — async domain OSINT investigation (start → poll → report)
  + osint_investigate_infrastructure_start  — async deep-infrastructure OSINT (domain, IP, or org)
  + osint_investigate_supply_chain_start    — async supply-chain OSINT investigation
  + osint_investigate_username_start        — async username OSINT (owner/enterprise tier only)
  + osint_investigate_email_start           — async email OSINT (owner/enterprise tier only)
  + osint_investigation_status   — poll status of any running OSINT investigation
  + osint_investigation_report   — retrieve report for a completed OSINT investigation

  Internal-only compatibility surface (withdrawn from public `tools/list`; the three active Microsoft 365 / Entra tools proxy through `BV_WEB` and degrade to unprovisioned without it):
  + query_signins                — query Microsoft Entra sign-in logs for a tenant
  + query_ual                    — DEPRECATED tombstone; valid, authorized calls return query_ual_deprecated with no tenant-data access
  + get_ca_policies              — retrieve Conditional Access policies for an Entra tenant
  + assess_coverage              — assess Conditional Access coverage gaps for an Entra tenant
  + map_registrar_products       — map a domain's gaps to registrar brand-protection products

Tool discovery metadata (`_meta`)

tools/list returns every tool with server-specific discovery metadata under each tool's _meta (the MCP-sanctioned extension point), so a client can group or filter the surface without hard-coding tool names:

group — functional group (email_auth, infrastructure, brand_threats, dns_hygiene, intelligence, remediation, discovery, identity_secops, meta).
tier — scoring tier (core / protective / hardening); absent for non-scoring tools.
scanIncluded — true when the tool runs inside scan_domain's parallel audit.
recommended — present (true) only on the curated starter set (scan_domain, explain_finding, compare_baseline); omitted otherwise. A client facing the full surface can lead with tools.filter(t => t._meta.recommended) to avoid overwhelming an LLM with all tools flat. Every tool is still listed — this is an additive signal, not a filter.

Authoritative DNS infrastructure

check_authoritative_dns_infra measures authoritative DNS infrastructure posture for a hostname over direct DNS-over-TCP/53 from a single vantage, via the BV_INFRA_PROBE service binding: TCP/53 reachability, the authoritative AA flag, recursion exposure, SOA serial consistency across nameservers, DNSKEY/RRSIG presence (not validation), IPv4/IPv6 answer parity, and unsupported-query handling. For authenticated callers only, it also runs a zone-transfer refusal test (first response only — no zone data is ever retrieved) and CHAOS version.bind/id.server disclosure. It does not measure, and reports as inconclusive: UDP/53 reachability, amplification, EDNS large-response/truncation, DNS cookies/RRL, BGP origin, RPKI, route-leak signals, anycast diversity, vantage latency, and RIR/RDAP.

check_root_server_set queries a rotating sample of 3 root servers per call and compares the priming NS set, glue, SOA serials, and cross-root consistency with the embedded official root hints, via BV_INFRA_PROBE.

Self-hosted or local deployments without BV_INFRA_PROBE still return structured partial results. The worker-only mode records the embedded root hints and marks every live-probe capability inconclusive rather than pretending it ran; both tools then withhold their verdict (checkStatus: 'error', excluded from scoring) instead of grading reference data.

Quality & Reliability

The server classifies detected MCP clients by their default response format:

Interactive clients: claude_mobile, claude_code, cursor, vscode, claude_desktop, claude_connector, windsurf (auto-format: compact)
Non-interactive clients: mcp_remote, blackveil_dns_action, bv_claude_dns_proxy, unknown (auto-format: full)

The bv_load_test class identifies internal load/chaos/tranco-scan traffic so it stays out of real-client analytics segments.

The comprehensive chaos suite validates session stability, authentication precedence, format negotiation, and transport-specific edge cases across Streamable HTTP and Legacy SSE for its supported client fixtures. Without an API key it exercises the public/free-tier path; with a valid key exported as BV_API_KEY, it covers Bearer authentication, legacy self-host ?api_key= compatibility, authenticated SSE bootstrap, and authenticated batch behavior.

Run the client/session chaos suite locally: python3 scripts/chaos/chaos-test-clients.py.

Run repeat force-refresh scans to detect production scoring drift:

BV_API_KEY=... python3 scripts/chaos/score-stability-test.py --count 20 --rounds 3 --concurrency 5

The stability harness negotiates MCP protocol 2025-06-18, accepts JSON and Streamable HTTP SSE responses, and exits non-zero on any transport/tool error or score/category drift. Use --from <json-file> with a JSON array of domains for a targeted provider-diversity sweep.

SSOT guardrails are enforced by focused audit tests:

Tool counts and public resource copy are generated from the TOOLS registry, not hand-written — npm run generate:tool-surface rewrites every advertised count, and npm run check:tool-surface fails CI if any drifts. Counts advertised to clients use the public surface (TOOLS minus internal-only tools), so the number in the docs, the badge, the VS Code listing and the resources/read copy is the number tools/list actually returns.
Domain-required validation is derived from each tool input schema.
Scan timeout budgets are resolved from shared runtime config.
WASM tool permissions are generated from MCP tool annotations.
Public quota copy is checked against runtime quota config.

Version stamps in scan output

Every scan_domain / batch_scan result carries three reproducibility stamps. They are three different namespaces — do not compare them to each other, and do not read any of them as the npm package version unless it says so:

Field	What it tracks	How often it moves
`scoringModelVersion`	The scoring policy: category weights, profile weights, grade thresholds, severity penalties, the `passed`/missing-control rule, profile detection.	Only when a change alters scores or grades. Slowly — most releases do not touch it.
`dnsChecksPackageVersion`	The `@blackveil/dns-checks` engine package version bundled by the running build.	Every package release — code, new detections, bug fixes.
`scoringConfigHash`	Fingerprint of the effective scoring configuration that produced this result, including any `SCORING_CONFIG` override.	Whenever the effective config differs.

scoringModelVersion is independent of dnsChecksPackageVersion and is normally lower — for example model 1.10.0 alongside package 1.18.0. That is not a version gap, and it does not mean a consumer's vendored copy scores differently from the hosted service: the package advanced eight minors without changing scoring policy. Reading the model version as the package version has twice triggered a false "engine version gap" investigation, which is why both are now emitted side by side.

When you publish or cite a score, record scoringConfigHash — not either version number. It is the value that identifies the exact scoring configuration behind a result, so two scans carrying the same hash were graded under the same rules.

Status badge

GET /badge/<domain> returns an embeddable SVG — the badge at the top of this README is a live scan of our own domain. It needs no authentication and is subject to the same anonymous rate limits and daily caps as a public scan.

The badge shows the same customer-facing letter scan_domain reports — the NIST-aligned 6-band grade (A+ ≥95, A ≥90, B ≥80, C ≥70, D ≥60, F <60) — so a domain cannot show one grade on its badge and a different one in its report. Two further states are stated rather than papered over:

<grade> partial — the scan was graded, but did not complete every check (a WAF challenge, a timeout, an unreachable host). The hover/aria title gives the exact coverage, e.g. 17 of 19 checks measured. The grade and its colour are unchanged: coverage and posture are different axes.
unknown — the domain could not be measured at all. The badge says so instead of substituting a letter, which would publish a failing grade nobody measured.

See docs/scoring.md for the grade scales and the evidence rules behind them.

Architecture

  MCP Client
      │
      │  POST /mcp (JSON-RPC 2.0)
      │
  ┌───▼──────────────────────┐
  │  Cloudflare Worker       │
  │                          │
  │  Hono ─► Origin check    │
  │       ─► Auth            │
  │       ─► Rate limiting   │
  │       ─► Session mgmt    │
  └───┬──────────────────────┘
      │
  ┌───▼──────────────────────┐
  │  Tool Handlers           │
  │  19 scoring categories   │
  └───┬──────────────────────┘
      │
  ┌───▼──────────────────────┐
  │  Generic Scoring Engine  │
  │  Three-tier model        │
  └───┬──────────────────────┘
      │
  ┌───▼──────────────────────┐
  │  Cloudflare DoH          │
  │  DNS-over-HTTPS          │
  └──────────────────────────┘

Generic Scoring Engine: Runtime-agnostic, string-keyed three-tier scoring with configurable weights
Infra Probe Binding: Optional BV_INFRA_PROBE service binding supplies live DNS-over-TCP/53 authoritative DNS and root-server evidence for the authoritative DNS infrastructure profile
CT Index Binding: Optional BV_CERTSTREAM service binding supplies Certificate Transparency names for discover_subdomains and SAN correlation. Operator deployments point it at the owned bv-ct-index sidecar (packages/bv-ct-index), a forward-only names index built from the public CT logs; source order stays binding, then crt.sh, then CertSpotter, then the last-known-good cache, so the direct sources remain the fallback. See docs/bv-ct-index-runbook.md
WASM Policy Engine: High-performance permission and token checks via bv-wasm-core
Reliable Sessions: Hardened tombstone logic prevents race-condition revival of terminated sessions
Protocol Enforcement: Unsupported MCP versions fail closed; notifications and SSE connections use the same session-validity rules as other post-initialize requests
Bounded Egress: Public CT and target-HTML responses are streamed under byte ceilings before parsing or fingerprinting
Cryptographic Identifiers: Session and brand-report identifiers use Web Crypto randomness
Adaptive Scoring: Durable Object telemetry adjusts weights based on real-world distributions
Client Awareness: Automatic response formatting (compact vs full) based on client User-Agent

Brand-discovery modes (`discover_brand_domains` / `brand_audit_*`)

The discovery_mode argument accepts two values:

classic (the default everywhere this repo runs out-of-the-box) — the public, BUSL-licensed signal-sweep pipeline. Uses only public-internet data sources (DNS, RDAP, CT logs, MX/TXT inspection). This is the only mode supported for self-hosted deployments and the only mode the open test suite covers end-to-end.
tiered — layers a portfolio-aware Tier 0 / infrastructure-graph Tier 1 / declared-evidence Tier 2 pipeline in front of the classic sweep. Tiered mode requires private BlackVeil-internal cross-Worker bindings (BV_INFRA_GRAPH, BV_INTEL_GATEWAY, BV_ENTERPRISE) that are not packaged with the open distribution — they live in BlackVeil's production deploy overlay (.dev/wrangler.deploy.jsonc) and call into proprietary Workers. Self-hosters cannot enable tiered mode without those bindings.

BlackVeil's hosted production at dns-mcp.blackveilsecurity.com flips its runtime default to tiered via the env var BRAND_AUDIT_DISCOVERY_MODE_DEFAULT="tiered" in the private overlay; the public schema default in src/schemas/tool-args.ts stays 'classic' permanently so anyone building from main gets the BUSL-licensed behaviour unchanged. An explicit caller-supplied discovery_mode always wins over the env default.

Client setup

The free tier requires no authentication. Authenticated requests bypass per-IP rate limits and follow your tier's daily quota. Hosted production supports:

Header: Authorization: Bearer <KEY>
Header (alternative): X-API-Key: <KEY> — for clients that cannot set Authorization. If both are sent, Authorization: Bearer wins.
OAuth 2.1: optional authorization-code flow with PKCE, enabled only when operators set ENABLE_OAUTH=true; owner-key consent is separately gated by ENABLE_OWNER_OAUTH=true.

The ?api_key=<KEY> fallback is legacy/self-host compatibility only. BlackVeil hosted production sets REJECT_QUERY_API_KEY=true; clients that cannot send headers should use OAuth or an mcp-remote header bridge.

For full hosted setup examples, stdio usage, OAuth setup, and legacy fallback endpoints, see docs/client-setup.md.

CLI

This repository's root package ships a blackveil bin (src/cli.ts, built to dist/cli.js): a client for the hosted endpoint, not a local scanner. It calls https://dns-mcp.blackveilsecurity.com/mcp and works without a key; set BLACKVEIL_API_KEY to use a keyed tier's quota (keys are never accepted on the command line). BLACKVEIL_MCP_URL overrides the endpoint (HTTPS required except loopback).

blackveil scan example.com --format json
blackveil check spf example.com
blackveil batch --file domains.txt --fail-below 70
blackveil policy example.com --policy policy.json
blackveil drift save example.com --out baseline.json
blackveil drift compare example.com --baseline baseline.json
blackveil evidence verify baseline.json

Commands: scan, check, batch, policy, drift save|compare, evidence verify. Output formats (--format): human (default), json, ndjson, evidence; --out <file> writes to a file, --fail-below <0-100> or --policy <file> turns a scan into a pass/fail gate. Exit codes: 0 pass, 1 verified policy or integrity failure, 2 usage/input, 3 auth/quota/transport/tool error, 4 ungraded/inconclusive. blackveil --help prints the full usage (source of truth: src/cli/command.ts).

The npm package blackveil-dns is frozen at 2.13.0 (published 2026-05-12), and that artifact carries only the blackveil-dns-mcp stdio bin, not blackveil, so npm i -g blackveil-dns does not install this CLI. Publishing is closed by policy (#719, closed as not planned). Build from source (npm ci && npm run build) for the CLI, or use blackveil-dns-action in CI; it calls the hosted endpoint and needs no npm package.

REST / HTTP

The hosted engine is also reachable without MCP framing through BlackVeil's public API (pointer only; the API's own docs are authoritative):

Keyless single checks: POST https://www.blackveilsecurity.com/api/v1/tools/lookup — OpenAPI spec at https://www.blackveilsecurity.com/openapi.json.
Keyed, metered full scan: POST https://www.blackveilsecurity.com/api/scan/v1/scan with a tenant API key, on plans that include API access (see Pricing).

Operator configuration

These settings apply to operators running their own deployment. They are optional — self-hosted (BUSL) deployments fall back to privacy-preserving defaults when they are unset.

Detailed analytics capture

The public /mcp path writes a per-event access log enriched with geolocation and network identity. The write path, PII depth, and retention are operator-controlled:

Binding / var	Type	Purpose
`MCP_ANALYTICS_QUEUE`	Queue	Operator-deploy only. Batches access-log writes off the request path. Absent on self-hosts → inline-insert fallback (no reverse-DNS lookup).
`ANALYTICS_PII_LEVEL`	var	`coarse` (default) \| `standard` \| `full`. Controls access-log PII depth: `coarse` = country/region/ASN + hashed/masked IP; `standard` adds encrypted IP + city; `full` adds lat/long + reverse-DNS (PTR).
`ANALYTICS_RETENTION_DAYS`	var	Access-log retention window in days (default `90`, clamped `1`–`365`). Rows older than the window are pruned by the scheduled handler.
PTR third-party disclosure	—	At `ANALYTICS_PII_LEVEL=full`, caller-IP PTR lookups resolve through the configured DoH chain, whose final fallback is Google Public DNS — an external disclosure of caller-IP-derived queries that operators should weigh before enabling `full`. Per-subject erasure: `POST /internal/analytics/erase?key_hash=…\|ip_hash=…` (strict internal bearer; self-audited).

Internal analytics endpoints

These live under the internal auth gate (/internal/*) and are called by bv-web, not the public surface:

Endpoint	Source	Notes
`GET /internal/analytics/usage?days=&key_hash=`	D1	Precise per-customer usage report.
`GET /internal/analytics/geo?days=`	Analytics Engine	Geographic rollup (country/region/city/ASN) for dashboards.
`GET /internal/analytics/forensics?days=&ip_hash=&key_hash=`	D1	STRICT-gated, operator-only. Returns decrypted client IP + PTR for abuse investigation; every call writes a self-audit row.

Pricing

	Free	Developer	Enterprise
Price	$0	$39/mo (provisioned by BlackVeil, not self-serve checkout)	Contact us
Scans/day	25 (anonymous, per IP); 50 with a free key	500 per tool	10,000+ per tool
Checks/day	Tool-specific limits	Tool-specific limits	Contract limits
Rate limit	50 req/min	None	None
API access	No	Yes	Yes
MCP access	Yes	Yes	Yes

Free-tier daily limits depend on whether you send a key. Anonymous (no key): 25 scan_domain scans/day per IP, across at most 12 distinct domains/day. Free key: 50/day per tool. Free keys do not carry the REST scan API (see REST / HTTP); "API access" above means that keyed API. Limits are read from TIER_DAILY_LIMITS, FREE_TOOL_DAILY_LIMITS and FREE_DISTINCT_DOMAIN_DAILY_LIMIT in src/lib/config.ts.

Offensive/recon and multi-domain tools (subdomain discovery, attack-path simulation, lookalike/shadow-domain detection, fast-flux detection, supply-chain mapping, real-time threat feed, bucket/OSINT investigations, batch_scan, compare_domains, brand audits) require a paid plan (Developer tier or higher); free, unauthenticated, and agent-tier callers get an HTTP 403 upgrade-required response. Unauthenticated callers are additionally capped at 12 distinct domains per day (best-effort, fail-open). The OSINT/bucket status and report pollers stay free; the brand-audit and brand-discovery pollers (brand_audit_status, brand_audit_get_report, discover_brand_domains_status, discover_brand_domains_findings) have no unauthenticated allowance and return HTTP 429 without a key.

Example prompts

These demonstrate core functionality — paste any of them into Claude with the Blackveil DNS connector enabled:

Prompt	What it does
`Scan blackveilsecurity.com and tell me what needs fixing`	Full security audit — score, grade, prioritized findings
`Compare the email security of google.com and microsoft.com`	Side-by-side comparison of two domains' postures
`Generate a DMARC record for example.com with reject policy`	Produces a ready-to-publish DNS record
`What attack paths exist for example.com?`	Enumerates spoofing, takeover, and hijack vectors
`Map example.com's compliance against NIST 800-177`	Maps findings to compliance framework controls

Support

Bug reports & feature requests: GitHub Issues
Security vulnerabilities: [email protected] (see SECURITY.md)
General questions: GitHub Discussions
Support the project: Ko-fi — the hosted scanner is free to use; tips help keep it that way

Responsible use

This tool is intended for authorized security assessments of domains you own or have explicit permission to test. Do not use it for unauthorized reconnaissance, harassment, or any activity that violates applicable laws. Findings from attack simulation, spoofability, and subdomain discovery tools should be used to improve your own security posture, not to exploit others.

If you discover a vulnerability in a third-party domain, please follow coordinated disclosure practices.

Self-hosting and license

The supported self-host path is the stdio bin (blackveil-dns-mcp) for non-commercial use. The Cloudflare Worker configuration in this repository references BlackVeil-private bindings and is not a third-party deploy target. Under the LICENSE Additional Use Grant, providing the Licensed Work as a hosted service to third parties for a fee, or embedding it in a commercial product, is commercial use and needs a separate licence from BLACKVEIL. Commercial licences are available on request via https://blackveilsecurity.com/contact.

Built and maintained by BLACKVEIL — NZ-owned cybersecurity consultancy.

BlackVeil DNS & Email Security Scanner

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install BlackVeil DNS & Email Security Scanner?

Does BlackVeil DNS & Email Security Scanner need an API key?

What transport does BlackVeil DNS & Email Security Scanner use?

When was BlackVeil DNS & Email Security Scanner last checked?

Documentation

BLACKVEIL DNS

Try it in 30 seconds

What you get

Tools

Tool discovery metadata (`_meta`)

Authoritative DNS infrastructure

Quality & Reliability

Version stamps in scan output

Status badge

Architecture

Brand-discovery modes (`discover_brand_domains` / `brand_audit_*`)

Client setup

CLI

REST / HTTP

Operator configuration

Detailed analytics capture

Internal analytics endpoints

Pricing

Example prompts

Support

Responsible use

Self-hosting and license

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install BlackVeil DNS & Email Security Scanner?

Does BlackVeil DNS & Email Security Scanner need an API key?

What transport does BlackVeil DNS & Email Security Scanner use?

When was BlackVeil DNS & Email Security Scanner last checked?

Documentation

BLACKVEIL DNS

Try it in 30 seconds

What you get

Tools

Tool discovery metadata (_meta)

Authoritative DNS infrastructure

Quality & Reliability

Version stamps in scan output

Status badge

Architecture

Brand-discovery modes (discover_brand_domains / brand_audit_*)

Client setup

CLI

REST / HTTP

Operator configuration

Detailed analytics capture

Internal analytics endpoints

Pricing

Example prompts

Support

Responsible use

Self-hosting and license

Tool discovery metadata (`_meta`)

Brand-discovery modes (`discover_brand_domains` / `brand_audit_*`)