domain-audit

Comprehensive domain health auditing tool

DNS • SSL/TLS • Subdomains • HTTP Headers • WHOIS • Ports • Email Security • Tech Detection

This is an experimental/learning project and should not be considered production-grade software. It is shared for educational purposes, personal exploration, and as a foundation for further development. Use at your own risk — results may be incomplete or inaccurate. Contributions and feedback are welcome.

Scan any domain and get an instant health report with A-F grades and actionable fix recommendations. Built for sysadmins and DevOps engineers. No API keys required.

╔═══════════════════════════════════════════════════════════╗
║         DOMAIN AUDIT: example.com                         ║
║         Overall Grade: B                                  ║
╠═══════════════════════════════════════════════════════════╣
║ Subdomains        │  -  │ 12 discovered                   ║
║ DNS Records       │  A  │ All records found                ║
║ SSL/TLS           │  A  │ Valid, 142 days left             ║
║ HTTP Headers      │  C  │ Missing CSP, HSTS               ║
║ WHOIS             │  A  │ 364 days until expiry            ║
║ Open Ports        │  A  │ 2 open, 10 closed, 4 filtered   ║
║ Email Security    │  F  │ No DMARC record                  ║
║ Tech Stack        │  -  │ Cloudflare, Next.js, Stripe      ║
╠═══════════════════════════════════════════════════════════╣
║ ACTION ITEMS:                                             ║
║ 1. [CRITICAL] Add DMARC record                           ║
║ 2. [HIGH] Add Content-Security-Policy header              ║
║ 3. [HIGH] Enable HSTS                                     ║
╚═══════════════════════════════════════════════════════════╝

Quick Start

Try in Google Colab (zero install)

Click the badge, enter a domain, run. That's it.

Install locally

pip install domain-audit

Or install from source (latest development version):

pip install git+https://github.com/Opticsponge/domain-audit.git

CLI Usage

# Full audit
domain-audit example.com

# Specific scanners only
domain-audit example.com --only ssl,dns,headers

# JSON output (great for CI/CD and AI agents)
domain-audit example.com --format json

# CSV export
domain-audit example.com --format csv -o results.csv

# Custom tech detection patterns
domain-audit example.com --tech-patterns my_patterns.json

MCP Server (AI Agent Integration)

domain-audit ships as an MCP (Model Context Protocol) server, allowing AI agents to invoke domain scans as tools.

Setup

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "domain-audit": {
      "command": "domain-audit-mcp"
    }
  }
}

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "domain-audit": {
      "command": "domain-audit-mcp"
    }
  }
}

Works with any MCP-compatible client (Cursor, Cline, etc.) using the same config pattern.

Available Tools

Example Tool Response

Each tool returns structured JSON. For example, scan_ssl("example.com") returns:

{
  "module": "ssl",
  "status": "pass",
  "grade": "A",
  "findings": [
    {"label": "Certificate", "grade": "A", "detail": "Valid, expires in 364 days", "fix": ""}
  ],
  "raw_data": { "issuer": "Let's Encrypt", "not_after": "2027-04-11", ... },
  "elapsed": 1.2
}

audit_domain returns all module results plus overall_grade and action_items.

Python API

from domain_audit import audit

results = audit("example.com")

# Structured dict (AI-friendly)
data = results.to_dict()

# Export
results.to_json("audit.json")
results.to_csv("audit.csv")

What It Checks

Grading System

Overall grade = weighted average across scored modules (SSL 25%, DNS 15%, Email 15%, Headers 15%, WHOIS 10%, Ports 10%). Tech and Subdomains are informational.

Action items are auto-generated for any check below grade A, sorted by severity: CRITICAL > HIGH > MEDIUM > LOW

Features

• Parallel scanning — subdomain discovery runs first, then all remaining modules run concurrently via thread pool
• Retry with backoff — exponential backoff + jitter on transient network failures
• Per-scanner timeouts — tuned defaults (3s-15s) so one slow scanner won't block the rest
• Per-subdomain probing — discovered subdomains get DNS, SSL, HTTP scans with data-type-specific tables
• MXToolbox-style reports — parsed record tables (Tag/Value/Name/Description) + validation test rows with pass/fail checkmarks
• Structured output — JSON and CSV export for CI/CD pipelines and AI agents
• Colab-native — rich color-coded HTML with summary table, expand/collapse, and detailed drill-down
• XSS-safe — all user data HTML-escaped in Colab renderer
• Zero API keys — everything works out of the box, no signup required
• AI-friendly — results.to_dict() returns clean structured data any LLM can parse

Available Scanners

dns         DNS records (A, AAAA, MX, NS, TXT, CNAME, SOA, SRV, CAA) + zone transfer test
subdomains  CT log discovery + per-subdomain DNS/SSL/HTTP probes with data tables
ssl         SSL/TLS certificate health, expiration, hostname match, protocol check
headers     Security headers + redirect chain analysis + cookie security flags
whois       WHOIS registration, domain expiry, name servers
ports       16-port scan across main domain + subdomains (HTTP, HTTPS, SSH, SMTP, MSSQL, MySQL, RDP, PostgreSQL, Elasticsearch, MongoDB)
email       SPF/DKIM/DMARC with parsed record tables, validation tests, SPF lookup chain counting
tech        6-source fingerprinting: headers, meta tags, URL paths, CDN/asset URLs, inline JS, DNS records

Run specific ones with --only:

domain-audit example.com --only ssl,email,headers

Tech Stack Detection

The tech scanner uses 6 detection sources to identify ~150 technologies:

Results are grouped into categories: Server/Hosting, Framework/CMS, UI/CSS, Analytics/Marketing, Developer/API Tools, Email/Transactional, Business Tools, Monitoring/Ops, and more.

Custom Tech Patterns

Add your own detection patterns via Python API, CLI, or MCP:

Python API:

from domain_audit import audit

result = audit("example.com", tech_patterns={
    "cdn_domains": [
        {"pattern": "my-cdn.corp.com", "name": "CorpCDN", "category": "Server / Hosting"},
    ],
    "asset_paths": [
        {"pattern": r"my-framework[.\-]", "name": "MyFramework", "category": "Framework / CMS"},
    ],
    "inline_js": [
        {"pattern": "__MY_APP__", "name": "MyApp"},
    ],
    "headers": [
        {"pattern": "X-My-Platform", "name": "", "category": "Server / Hosting"},
    ],
    "paths": [
        {"pattern": "/my-admin/", "name": "MyPlatform"},
    ],
})

CLI with JSON file:

domain-audit example.com --tech-patterns patterns.json

{
  "cdn_domains": [
    {"pattern": "internal-cdn.corp.com", "name": "Internal CDN", "category": "Server / Hosting"}
  ],
  "asset_paths": [
    {"pattern": "my-framework[.\\-]", "name": "MyFramework", "category": "Framework / CMS"}
  ]
}

Pattern types:

Each pattern: {"pattern": "...", "name": "TechName", "category": "Optional Category"}. Category defaults to "Other" if omitted. Patterns are additive — they extend the built-in set, never replace it.

Output Formats

Development

git clone https://github.com/Opticsponge/domain-audit.git
cd domain-audit
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

Project Structure

domain_audit/
├── __init__.py          # Public API: audit(), AuditResult, ScanResult, TechPatterns
├── cli.py               # CLI entry point
├── core.py              # Orchestrator — two-phase parallel scanner execution
├── grader.py            # Grading logic + action item generation
├── retry.py             # Retry decorator with exponential backoff
├── report.py            # Terminal (Rich) and Colab (HTML) renderers
├── report_tables.py     # Category-based HTML report tables
└── scanners/
    ├── dns_records.py   # DNS enumeration
    ├── subdomains.py    # CT log subdomain discovery
    ├── ssl_check.py     # SSL/TLS certificate checks
    ├── headers.py       # HTTP security headers
    ├── whois_info.py    # WHOIS lookup
    ├── ports.py         # Port scanning (main domain + subdomains)
    ├── email_security.py # SPF/DKIM/DMARC
    ├── tech_detect.py   # Technology fingerprinting (loads patterns from JSON)
    └── tech_patterns/   # Standalone JSON pattern files (easy to PR)
        ├── cdn_domains.json   # CDN/hosting domain → tech mapping
        ├── asset_paths.json   # JS/CSS URL regex → tech mapping
        ├── inline_js.json     # Inline JS globals → tech mapping
        ├── dns_txt.json       # TXT record patterns → tech mapping
        ├── dns_cname.json     # CNAME target patterns → tech mapping
        ├── headers.json       # Response header → tech mapping
        ├── paths.json         # URL path → tech mapping
        ├── meta_tags.json     # Meta tag patterns → tech mapping
        └── categories.json    # Tech name → display category grouping

Contributing

See CONTRIBUTING.md for development setup, code quality tools, fork workflow, and submission guidelines.

License

MIT

Made with Python • GitHub • Try in Colab