{"id":46663572,"url":"https://github.com/madaburns/bv-mcp","last_synced_at":"2026-05-30T09:01:08.901Z","repository":{"id":343012731,"uuid":"1164356138","full_name":"MadaBurns/bv-mcp","owner":"MadaBurns","description":"Open-source DNS \u0026 email security scanner. One MCP endpoint, 57 checks, zero install. Cloudflare Workers.","archived":false,"fork":false,"pushed_at":"2026-05-24T07:31:31.000Z","size":18750,"stargazers_count":7,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T08:23:17.096Z","etag":null,"topics":["agentic","ai","ai-tools","cloudflare-workers","cybersecurity","dkim","dmarc","dns-security","email-security","llm","mcp","mcp-server","model-context-protocol","saas","security-scanner","spf"],"latest_commit_sha":null,"homepage":"https://blackveilsecurity.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MadaBurns.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-23T01:32:53.000Z","updated_at":"2026-05-24T07:31:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"003ec2b5-059b-41dd-9acb-61966582652e","html_url":"https://github.com/MadaBurns/bv-mcp","commit_stats":null,"previous_names":["madaburns/bv-mcp"],"tags_count":109,"template":false,"template_full_name":null,"purl":"pkg:github/MadaBurns/bv-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadaBurns%2Fbv-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadaBurns%2Fbv-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadaBurns%2Fbv-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadaBurns%2Fbv-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MadaBurns","download_url":"https://codeload.github.com/MadaBurns/bv-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadaBurns%2Fbv-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33686018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai","ai-tools","cloudflare-workers","cybersecurity","dkim","dmarc","dns-security","email-security","llm","mcp","mcp-server","model-context-protocol","saas","security-scanner","spf"],"created_at":"2026-03-08T15:01:15.125Z","updated_at":"2026-05-30T09:01:08.895Z","avatar_url":"https://github.com/MadaBurns.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# BLACK**V**EIL DNS\n\n**Know where you stand.**\n\nSource-available DNS \u0026 email security scanner for Claude, Cursor, VS Code, and MCP clients across Streamable HTTP, stdio, and legacy HTTP+SSE.\n\n[![GitHub stars](https://img.shields.io/github/stars/MadaBurns/bv-mcp?style=flat\u0026logo=github)](https://github.com/MadaBurns/bv-mcp/stargazers)\n[![npm version](https://img.shields.io/npm/v/blackveil-dns)](https://www.npmjs.com/package/blackveil-dns)\n[![npm downloads](https://img.shields.io/npm/dm/blackveil-dns)](https://www.npmjs.com/package/blackveil-dns)\n[![MCP tools](https://img.shields.io/badge/MCP%20tools-78-brightgreen)](https://github.com/MadaBurns/bv-mcp/actions)\n[![BUSL-1.1 License](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-2025--03--26-blue)](https://modelcontextprotocol.io/)\n[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-F38020?logo=cloudflare\u0026logoColor=white)](https://workers.cloudflare.com/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n\n![DNS Security](https://dns-mcp.blackveilsecurity.com/badge/blackveilsecurity.com)\n\n\u003c/div\u003e\n\n---\n\n## Try it in 30 seconds\n\n**Claude Desktop** (one-click install):\n\nDownload the [Blackveil DNS extension](https://github.com/MadaBurns/bv-claude-dns/releases/latest/download/bv-claude-dns.mcpb) and open it — the current 78-tool surface is available instantly. [Verify your download](https://blackveilsecurity.com/extensions/claude-dns#install).\n\n**Claude Code** (one command):\n\n```bash\nclaude mcp add --transport http blackveil-dns https://dns-mcp.blackveilsecurity.com/mcp\n```\n\nThen ask: `scan anthropic.com`\n\n**Smithery** (one command):\n\n```bash\nsmithery mcp add MadaBurns/bv-mcp\n```\n\n**Verify the endpoint is live:**\n\n```bash\ncurl https://dns-mcp.blackveilsecurity.com/health\n```\n\nNo install. No API key. One URL for hosted HTTP:\n\n```\nEndpoint   https://dns-mcp.blackveilsecurity.com/mcp\nTransport  Streamable HTTP · JSON-RPC 2.0\nAuth       None required\n```\n\nTransport support:\n\n- `Streamable HTTP`: `POST /mcp`, `GET /mcp`, `DELETE /mcp`\n- `Native stdio`: `blackveil-dns-mcp` CLI from the `blackveil-dns` npm package\n- `Legacy HTTP+SSE`: `GET /mcp/sse` bootstrap stream plus `POST /mcp/messages?sessionId=...`\n\n---\n\n## What you get\n\n- **78 MCP tools with 18 scoring categories** — SPF, DMARC, DKIM, DNSSEC, SSL/TLS, MTA-STS, NS, CAA, MX, BIMI, TLS-RPT, subdomain takeover, HTTP security headers, DANE, SVCB/HTTPS, subdomailing, brand discovery, and authoritative DNS infrastructure\n- **Maturity staging** — Stage 0-4 classification (Unprotected to Hardened) with score-based capping to prevent inflated labels\n- **Trust surface analysis** — detects shared SaaS platforms (Google, M365, SendGrid) and cross-references DMARC enforcement to determine real exposure\n- **Guided remediation** — `generate_fix_plan` produces provider-aware prioritized actions; record generators output ready-to-publish records; `validate_fix` confirms whether a fix was applied successfully\n- **Supply chain mapping** — `map_supply_chain` correlates DNS signals to build a full third-party dependency graph with trust levels and risk signals\n- **Attack path simulation** — `simulate_attack_paths` enumerates specific paths (spoofing, takeover, hijack) with severity, steps, and mitigations\n- **Compliance mapping** — `map_compliance` maps scan findings to NIST 800-177, PCI DSS 4.0, SOC 2, and CIS Controls\n- **Self-tuning scoring** — adaptive weights adjust category importance based on patterns seen across scans via Durable Object telemetry\n- **Per-tier analytics** — usage tracking by auth tier with operator API for tier summaries, key-level usage, and daily digests\n- **Passive and read-only** — all checks use public Cloudflare DNS-over-HTTPS; no authorization required from the target\n\n---\n\n## Tools\n\n```\n  78 MCP tools · 7 prompts · 6 resources\n\n  Email Auth             Infrastructure          Brand \u0026 Threats       Meta\n ─────────────          ──────────────          ───────────────       ───────────────\n  check_mx              check_dnssec            check_bimi            scan_domain\n  check_spf             check_ssl               check_tlsrpt          batch_scan\n  check_dmarc           check_ns                check_lookalikes      compare_domains\n  check_dkim            check_caa               check_shadow_domains  compare_baseline\n  check_mta_sts         check_http_security                           explain_finding\n  check_subdomailing    check_dane\n  check_mx_reputation   check_dane_https        DNS Hygiene           Remediation\n                        check_svcb_https       ─────────────         ───────────────\n  Intelligence          check_srv               check_txt_hygiene     generate_fix_plan\n ─────────────          check_zone_hygiene                            generate_spf_record\n  get_benchmark         check_resolver_         Discovery             generate_dmarc_record\n  get_provider_           consistency          ─────────────         generate_dkim_config\n    insights                                    discover_brand_       generate_mta_sts_policy\n  assess_spoofability   check_dbl                domains             validate_fix\n  map_supply_chain      check_rbl               brand_audit_single    generate_rollout_plan\n  analyze_drift         cymru_asn               brand_audit_batch_\n  resolve_spf_chain     rdap_lookup               start\n  discover_subdomains   check_nsec_             brand_audit_status\n  map_compliance          walkability           brand_audit_get_\n  simulate_attack_paths check_dnssec_chain        report\n                        check_fast_flux         list_brand_audit_watches\n                        check_dnskey_strength\n                        check_authoritative_dns_infra\n                        check_root_server_set   register_brand_audit_watch\n                                                delete_brand_audit_watch\n\n  + check_subdomain_takeover (standalone tool + internal — runs inside scan_domain)\n  + check_authoritative_dns_infra and check_root_server_set (authoritative DNS infrastructure profile)\n\n  Operator-deploy only (BV_RECON binding; degrade to unprovisioned on self-hosted BSL deployments):\n  + check_realtime_threat_feed   — curated intel-gateway threat feed lookup\n  + scan_buckets_start           — async cloud-bucket discovery scan (start → poll → findings)\n  + scan_buckets_status          — poll status of a running bucket scan\n  + scan_buckets_findings        — retrieve findings for a completed bucket scan\n  + osint_investigate_domain_start          — async domain OSINT investigation (start → poll → report)\n  + osint_investigate_infrastructure_start  — async deep-infrastructure OSINT (domain, IP, or org)\n  + osint_investigate_supply_chain_start    — async supply-chain OSINT investigation\n  + osint_investigate_username_start        — async username OSINT (owner/enterprise tier only)\n  + osint_investigate_email_start           — async email OSINT (owner/enterprise tier only)\n  + osint_investigation_status   — poll status of any running OSINT investigation\n  + osint_investigation_report   — retrieve report for a completed OSINT investigation\n```\n\n### Authoritative DNS infrastructure\n\n`check_authoritative_dns_infra` scores authoritative DNS hosting behavior for a hostname. It is designed to consume raw UDP/TCP DNS, authoritative AA/RA behavior, zone-transfer refusal, DNSSEC, abuse-resistance, BGP/RPKI, and multi-vantage evidence from the `BV_INFRA_PROBE` service binding when that worker is provisioned.\n\n`check_root_server_set` validates the DNS root-server set against the embedded official root hints. With `BV_INFRA_PROBE`, it also checks live root priming, glue, parent/child delegation, DNSKEY, and SOA serial evidence across roots.\n\nSelf-hosted or local deployments without `BV_INFRA_PROBE` still return structured partial results. The worker-only mode records the embedded root hints and marks live raw-DNS, routing, RPKI, and vantage capabilities as inconclusive rather than pretending they ran.\n\n---\n\n## Quality \u0026 Reliability\n\nThe server is continuously validated using a **comprehensive chaos test suite** that covers all detected MCP client types:\n\n- **Interactive clients**: `claude_code`, `cursor`, `vscode`, `claude_desktop`, `windsurf` (auto-format: `compact`)\n- **Non-interactive clients**: `mcp_remote`, `blackveil_dns_action`, `bv_claude_dns_proxy`, `unknown` (auto-format: `full`)\n\nThe `bv_load_test` class identifies internal load/chaos/tranco-scan traffic so it stays out of real-client analytics segments.\n\nThe test suite ensures session stability, authentication precedence, format negotiation, and transport-specific edge cases across Streamable HTTP and Legacy SSE. Without an API key it exercises the public/free-tier path; with a valid key exported as `BV_API_KEY`, it also covers `?api_key=` authentication, Bearer precedence, authenticated SSE bootstrap, and authenticated batch behavior.\n\nRun the chaos tests locally: `python3 scripts/chaos/chaos-test-clients.py`\n\nSSOT guardrails are enforced by focused audit tests:\n\n- Tool counts and public resource copy are derived from the `TOOLS` registry.\n- Domain-required validation is derived from each tool input schema.\n- Scan timeout budgets are resolved from shared runtime config.\n- WASM tool permissions are generated from MCP tool annotations.\n- Public quota copy is checked against runtime quota config.\n\n---\n\n## Architecture\n\n```\n  MCP Client\n      │\n      │  POST /mcp (JSON-RPC 2.0)\n      │\n  ┌───▼──────────────────────┐\n  │  Cloudflare Worker       │\n  │                          │\n  │  Hono ─► Origin check    │\n  │       ─► Auth            │\n  │       ─► Rate limiting   │\n  │       ─► Session mgmt    │\n  └───┬──────────────────────┘\n      │\n  ┌───▼──────────────────────┐\n  │  Tool Handlers           │\n  │  18 scoring categories   │\n  └───┬──────────────────────┘\n      │\n  ┌───▼──────────────────────┐\n  │  Generic Scoring Engine  │\n  │  Three-tier model        │\n  └───┬──────────────────────┘\n      │\n  ┌───▼──────────────────────┐\n  │  Cloudflare DoH          │\n  │  DNS-over-HTTPS          │\n  └──────────────────────────┘\n```\n\n- **Generic Scoring Engine**: Runtime-agnostic, string-keyed three-tier scoring with configurable weights\n- **Infra Probe Binding**: Optional `BV_INFRA_PROBE` service binding supplies raw authoritative DNS, root-server, BGP/RPKI, and vantage evidence for the authoritative DNS infrastructure profile\n- **WASM Policy Engine**: High-performance permission and token checks via `bv-wasm-core`\n- **Reliable Sessions**: Hardened tombstone logic prevents race-condition revival of terminated sessions\n- **Adaptive Scoring**: Durable Object telemetry adjusts weights based on real-world distributions\n- **Client Awareness**: Automatic response formatting (`compact` vs `full`) based on client `User-Agent`\n\n### Brand-discovery modes (`discover_brand_domains` / `brand_audit_*`)\n\nThe `discovery_mode` argument accepts two values:\n\n- **`classic`** (the default everywhere this repo runs out-of-the-box) — the public, BSL-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.\n- **`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.\n\nBlackVeil'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 BSL-licensed behaviour unchanged. An explicit caller-supplied `discovery_mode` always wins over the env default.\n\n---\n\n## Client setup\n\nThe free tier requires no authentication. Authenticated requests bypass per-IP rate limits and follow your tier's daily quota. Three authentication methods are supported:\n\n- **Header**: `Authorization: Bearer \u003cKEY\u003e`\n- **Query Param**: `?api_key=\u003cKEY\u003e` (for clients that can't send custom headers — Smithery, Claude Code)\n- **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`.\n\nFor full hosted setup examples, stdio usage, OAuth setup, and legacy fallback endpoints, see [**docs/client-setup.md**](docs/client-setup.md).\n\n---\n\n## Pricing\n\n|                | **Free**   | **Pro** | **Enterprise**                              |\n| -------------- | ---------- | ------- | ------------------------------------------- |\n| **Price**      | $0         | $39/mo  | [Contact us](https://blackveilsecurity.com) |\n| **Scans/day**  | 25         | 500     | 10,000+                                     |\n| **Checks/day** | Tool-specific limits | Tool-specific limits | Contract limits                  |\n| **Rate limit** | 50 req/min | None    | None                                        |\n| **API access** | Yes        | Yes     | Yes                                         |\n| **MCP access** | Yes        | Yes     | Yes                                         |\n\n---\n\n## Example prompts\n\nThese demonstrate core functionality — paste any of them into Claude with the Blackveil DNS connector enabled:\n\n| Prompt                                                       | What it does                                             |\n| ------------------------------------------------------------ | -------------------------------------------------------- |\n| `Scan blackveilsecurity.com and tell me what needs fixing`   | Full security audit — score, grade, prioritized findings |\n| `Compare the email security of google.com and microsoft.com` | Side-by-side comparison of two domains' postures         |\n| `Generate a DMARC record for example.com with reject policy` | Produces a ready-to-publish DNS record                   |\n| `What attack paths exist for example.com?`                   | Enumerates spoofing, takeover, and hijack vectors        |\n| `Map example.com's compliance against NIST 800-177`          | Maps findings to compliance framework controls           |\n\n---\n\n## Support\n\n- **Bug reports \u0026 feature requests:** [GitHub Issues](https://github.com/MadaBurns/bv-mcp/issues)\n- **Security vulnerabilities:** [security@blackveilsecurity.com](mailto:security@blackveilsecurity.com) (see [SECURITY.md](SECURITY.md))\n- **General questions:** [GitHub Discussions](https://github.com/MadaBurns/bv-mcp/discussions)\n\n---\n\n## Responsible use\n\nThis 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.\n\nIf you discover a vulnerability in a third-party domain, please follow [coordinated disclosure](https://www.cisa.gov/coordinated-vulnerability-disclosure-process) practices.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt and maintained by [**BLACKVEIL**](https://blackveilsecurity.com) — NZ-owned cybersecurity consultancy.\n\n[Privacy Policy](https://www.blackveilsecurity.com/privacy) · [License](LICENSE) (BUSL-1.1 → MIT on 2030-03-17)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadaburns%2Fbv-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadaburns%2Fbv-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadaburns%2Fbv-mcp/lists"}