domain-audit 0.1.0

Comprehensive domain health auditing tool — DNS, SSL, WHOIS, headers, ports, email security, and tech detection with actionable grades.

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

Tool	Description
audit_domain	Full audit — all or selected scanners
scan_dns	DNS records (A, AAAA, MX, NS, TXT, CAA)
scan_subdomains	CT log subdomain discovery
scan_ssl	Certificate and TLS checks
scan_headers	HTTP security headers
scan_whois	WHOIS/RDAP lookup
scan_ports	Open port detection
scan_email	SPF/DKIM/DMARC validation
scan_tech	Technology fingerprinting
list_scanners	List available scanners

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

Module	What It Scans	Grade
SSL/TLS	Certificate validity, expiration, hostname match, protocol version (flags TLS 1.0/1.1)	A-F
DNS Records	A, AAAA, MX, NS, TXT, CNAME, SOA, SRV, CAA + zone transfer (AXFR) test	A-F
Subdomains	Discovery via CT logs + per-subdomain DNS, SSL, HTTP probes with data tables	Informational
HTTP Headers	HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy + redirect chain analysis + cookie security flags	A-F
WHOIS	Registrar info, domain creation & expiration dates, name servers	A-F
Email Security	SPF (parsed tags + chain lookup limit), DKIM (36 selectors), DMARC (parsed tags + policy tests) — MXToolbox-style tables	A-F
Open Ports	16 ports across main domain + all discovered subdomains: FTP, SSH, SMTP, HTTP, HTTPS, MSSQL, MySQL, RDP, PostgreSQL, Elasticsearch (9200/9300), MongoDB (27017-27019), 8080, 8443	A-F
Tech Stack	6-source detection: response headers, meta tags, URL paths, asset/CDN URLs, inline JS markers, DNS records (TXT + CNAME) — ~150 built-in technologies + custom patterns	Informational

Grading System

Grade	Meaning	Example
A	Excellent	SSL cert valid, >90 days to expiry
B	Good, minor concern	SSL cert valid, 30-90 days to expiry
C	Needs attention	Missing HSTS header, weak SPF record
F	Failing	Expired SSL, open database port, no DMARC
?	Could not check	Scanner errored after retries

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:

Source	How It Works	Example
Response Headers	Checks Server, X-Powered-By, X-Generator, etc.	nginx, ASP.NET, Shopify
Meta Tags	Parses <meta name="generator">	WordPress 6.4
URL Paths	Finds CMS paths in page HTML (/wp-admin/, /administrator/)	WordPress, Joomla, Drupal
Asset URLs	Fingerprints <script src> / <link href> by CDN domain and filename	Webflow from CDN URL, React from bundle name
Inline JS	Detects framework globals (__NEXT_DATA__, Shopify., wixBiSession)	Next.js, Shopify, Wix
DNS Records	TXT verification records + CNAME targets reveal platforms and services	Google Workspace (SPF), Shopify (CNAME), Postman, Stoplight

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:

Key	Match Method	Use For
cdn_domains	Substring match on asset URLs	CDN domains, hosting platforms
asset_paths	Regex match on <script>/<link> URLs	JS libraries, framework bundles
inline_js	Regex match on page HTML	JS globals, framework markers
headers	Header name lookup (empty name → use header value)	Custom response headers
paths	Substring match in page HTML	CMS admin paths, known routes
dns_txt	Substring match on TXT records	Domain verification, SPF includes
dns_cname	Substring match on CNAME targets	Hosting, SaaS platform CNAMEs

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

Format	Use Case	Flag
Table	Terminal / human reading (default)	--format table
HTML	Auto-detected in Google Colab	(automatic)
JSON	CI/CD, APIs, AI agents	--format json
CSV	Spreadsheets, data analysis	--format csv

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