DomainDetective is a domain, DNS, email, web, and certificate security toolkit for people who want repeatable checks instead of one-off website lookups. It is built around the same analysis engine and exposed through three entry points:

• A C# library for custom automation and integrations
• A PowerShell module for operational scripts and reporting
• A .NET CLI for wizard-driven scans, batch usage, artifacts, and report generation

Most PowerShell checks expose both a fully-prefixed cmdlet and a friendly alias. For example, Test-DDEmailSpfRecord is also available as Test-EmailSpf.

• DNS and infrastructure: NS, SOA, MX, delegation, reverse DNS, FCrDNS, wildcard DNS, zone transfer, TTL, EDNS, open resolver, DNS over TLS, DNS health, DNS amplification, propagation, trace, and inventory.
• Email authentication and transport: SPF, DKIM, DMARC, ARC, BIMI, MTA-STS, TLS-RPT, SMTP TLS, STARTTLS, SMTP banner, SMTP auth posture, IMAP/POP3 TLS, open relay, email validation, and mail latency.
• Web and certificates: HTTP posture, certificate analysis, DANE/TLSA, S/MIMEA, static website scans, redirect chains, third-party inventory, header checks, tracker hints, and technology fingerprints.
• Registry, routing, and reputation: WHOIS, RDAP, RPKI, DNSBL, threat intel hooks, VirusTotal helpers, search engine checks, and domain suggestions/search.
• Discovery and exposure: CT timeline, subdomain discovery, certificate inventory, autodiscover, security.txt, contact TXT, directory exposure, and identity provider hints.
• Outputs and reporting: JSON, HTML, Word, Excel, Markdown, MarkdownHtml, and PDF, plus JSON artifacts for repeated runs and time-series stores.

flowchart LR
    A["PowerShell module"] --> D["DomainDetective core analyses"]
    B["CLI"] --> D
    C["C# library"] --> D
    D --> E["Views and JSON"]
    D --> F["Reports: HTML, Word, Excel, Markdown, PDF"]
    D --> G["Artifacts: scan.json, metrics.json, progress.jsonl"]
    D --> H["Stores: DMARC Aggregate, TLS-RPT, registration, cert inventory"]

Import the local module from the repository and run a few common checks:

Import-Module ./Module/DomainDetective.psd1 -Force

Test-DomainHealth -DomainName "example.com"
Test-EmailSpf -DomainName "example.com"
Test-Website -DomainName "example.com"

Export a report directly from a scan:

Import-Module ./Module/DomainDetective.psd1 -Force

Test-DomainHealth `
    -DomainName "example.com" `
    -ExportFormat Html `
    -ExportPath ".\artifacts\example-domain-report.html" `
    -OpenInBrowser

Compose multi-check reports from pipeline output:

Import-Module ./Module/DomainDetective.psd1 -Force

Export-DDSecurityReport -ExportFormat Word -ExportPath ".\artifacts\example-email-auth.docx" {
    Test-EmailSpf -DomainName "example.com"
    Test-EmailDkim -DomainName "example.com"
    Test-EmailDmarc -DomainName "example.com"
}

To discover the available PowerShell surface:

Get-Command -Module DomainDetective

The repository currently exposes the CLI as a normal .NET application, not as an installed global or local dotnet tool. The supported ways to run it today are:

• dotnet run --project DomainDetective.CLI -- ... while developing from source
• dotnet publish and then running the generated app from the publish directory

Run the interactive wizard:

dotnet run --project DomainDetective.CLI --

Run a direct health check:

dotnet run --project DomainDetective.CLI -- check example.com --json

Generate a report with artifacts:

dotnet run --project DomainDetective.CLI -- GenerateReport example.com --format html --output ./artifacts/example.html

A few other common entry points:

dotnet run --project DomainDetective.CLI -- AnalyzeMessageHeader --file ./headers.txt --json
dotnet run --project DomainDetective.CLI -- DnsPropagation --domain example.com --record-type A
dotnet run --project DomainDetective.CLI -- ValidateEmail [email protected] --smtp --catch-all
dotnet run --project DomainDetective.CLI -- --help

Publish a local copy of the CLI:

dotnet publish DomainDetective.CLI/DomainDetective.CLI.csproj -c Release -o ./artifacts/cli

Then run the published app:

.\artifacts\cli\DomainDetective.CLI.exe --help

./artifacts/cli/DomainDetective.CLI --help

Or use the build script introduced in this repository:

pwsh ./Build/Publish-CLI.ps1

That script publishes runtime-specific CLI artifacts under Artifacts/ProjectBuild/CLI and creates friendly aliases such as DD.exe on Windows and DD on Unix-like targets.

The example project in DomainDetective.Example shows many protocol-specific flows. The simplest library usage looks like this:

using DomainDetective;

var healthCheck = new DomainHealthCheck();
await healthCheck.Verify("example.com");

Console.WriteLine(healthCheck.ToJson());

• Raw: strongly-typed analysis models suitable for automation and downstream processing.
• Narrative: human-friendly summaries for CLI and PowerShell views.
• Highlights: concise status, counts, and key findings for quick review.

• DomainOrder: Alphabetical or Input
• SectionOrderMode: Canonical, Input, or Custom
• SectionOrder: explicit section keys when using Custom

Canonical per-domain section order:

MX, SPF, DKIM, DMARC, DMARC Aggregate, ARC, BIMI, DNSBL, RPKI, Registration, NS, SOA, TTL, ZoneTransfer, Wildcard, CAA, Classification, MTA-STS, TLS-RPT, TLS-RPT Reports, MAILTLS, DNSSEC, DANE

Executive summary columns remain canonical across formats; ordering affects per-domain sections only.

PowerShell:

Test-DDEmailAddress -EmailAddress "[email protected]" -SmtpProbe -CheckCatchAll

CLI:

dotnet run --project DomainDetective.CLI -- ValidateEmail [email protected] --smtp --catch-all --smtp-max-hosts 2

Custom SMTP rules:

Test-DDEmailAddress -EmailAddress "[email protected]" -SmtpProbe -SmtpRulesPath "./smtp-rules.json"

dotnet run --project DomainDetective.CLI -- ValidateEmail [email protected] --smtp --smtp-rules ./smtp-rules.json --no-builtin-smtp-rules

Useful controls:

• -EnableProviderWebChecks or --provider-web enables provider-specific web checks when available.
• -ProtonAuthCookie and -ProtonUid or --proton-auth and --proton-uid enable Proton-specific checks.
• -SmtpRulesPath or --smtp-rules supplies custom SMTP rules JSON.
• -DisableBuiltinSmtpRules or --no-builtin-smtp-rules ignores built-in SMTP rules.
• -AllowB2CCatchAll or --allow-b2c-catch-all allows catch-all probing for consumer providers.
• -AllowInvalidSmtpCertificates or --smtp-allow-invalid-cert skips SMTP TLS certificate validation.
• -SmtpTimeoutSeconds, -SmtpRetryDelaySeconds, and -SmtpProbeDelaySeconds tune SMTP timing and pacing.
• -B2CProvidersPath and -DisableFreeProvidersAsB2C control B2C provider classification behavior.

Notes:

• Built-in SMTP rules are enabled by default.
• See Docs/EmailSmtpRules.md for schema, examples, and Proton auth notes.
• Provider web checks rely on undocumented endpoints and may change or rate-limit without notice.
• Avoid passing Proton auth values through command history when possible.
• SMTP probing can trigger provider abuse protections during bulk runs.

PowerShell:

Import-Module ./Module/DomainDetective.psd1 -Force

Test-DomainHealth -DomainName "example.com" -ExportFormat Html -ExportPath ".\Reports\example.html"

CLI:

dotnet run --project DomainDetective.CLI -- GenerateReport example.com --format word --output ./Reports/example.docx

Use this path when you want a broad posture report covering DNS, email, web, certificates, and selected discovery sections.

Use Desired State when "best practice" is not enough and you need to compare domains to your own organization-specific baseline.

PowerShell:

Import-Module ./Module/DomainDetective.psd1 -Force

$baseline = New-DesiredState {
    New-DDDesiredStateSpf -Enabled $true -MaxDnsLookups 10
    New-DDDesiredStateDmarc -Enabled $true -AllowedPolicies reject
}

Test-DesiredState -DomainName "example.com" -Configuration $baseline

CLI:

dotnet run --project DomainDetective.CLI -- DesiredState example.com --desired-state ./desired-state.json --format html --output ./Reports/desired-state.html

Deep dive: Docs/DESIRED_STATE.MD

Use certificate inventory when you need portfolio-wide visibility, persistence, drift tracking, or policy/risk reporting across many domains and endpoints.

PowerShell:

Import-Module ./Module/DomainDetective.psd1 -Force

Invoke-DDCertificateInventory `
    -DomainName "example.com","example.org" `
    -CacheDirectory .\cert-monitor `
    -ReuseRecentResults `
    -RecentResultTtlHours 24 `
    -IncludeCtSubdomains `
    -VerifyCtSubdomains

CLI:

dotnet run --project DomainDetective.CLI -- CertificateInventoryCapture example.com example.org --include-ct-subdomains --verify-ct-subdomains
dotnet run --project DomainDetective.CLI -- CertificateInventorySummary --since-utc 2026-01-01
dotnet run --project DomainDetective.CLI -- CertificateInventoryRisk --expiring-within-days 30 --json

Deep dive: Docs/CERTIFICATE_INVENTORY.MD

DomainDetective can persist DMARC aggregate, TLS-RPT, and registration snapshots so reports can include historical sections instead of only point-in-time checks.

dotnet run --project DomainDetective.CLI -- ImportDmarcAggregateSnapshot ./Reports/DMARC --store-path ./Store
dotnet run --project DomainDetective.CLI -- ImportTlsRptReportSnapshot example.com ./Reports/TLSRPT --store-path ./Store
dotnet run --project DomainDetective.CLI -- ImportRegistrationSnapshot example.com --store-path ./Store
dotnet run --project DomainDetective.CLI -- GenerateReport example.com --format html --store-path ./Store

Coordinated runs emit structured artifacts under artifacts/<subject>/<timestamp>/.

Typical files:

• scan.json: metadata, summary, recommendations, and the full DomainHealthCheck
• metrics.json: counters and timing
• progress.jsonl: progress stream for long-running runs
• index.jsonl: subject-level run index used by RunsList and RunsOpen

List or open recent CLI runs:

dotnet run --project DomainDetective.CLI -- RunsList --subject example.com --count 5
dotnet run --project DomainDetective.CLI -- RunsOpen --subject example.com

Compose any mix of exportable views through the pipeline:

Import-Module ./Module/DomainDetective.psd1 -Force

$spf = Test-DDEmailSpfRecord -DomainName "evotec.pl"
$dnsbl = Test-DDDnsBlacklist -NameOrIpAddress "evotec.pl"

($spf + $dnsbl) | Export-DDSecurityReport -Scope Detailed -ExportFormat Word -ExportPath .\Reports -OpenReport

Or use an inline script block:

Import-Module ./Module/DomainDetective.psd1 -Force

Export-DDSecurityReport -Scope Detailed -ExportFormat Markdown -ExportPath .\Reports {
    Test-DDEmailSpfRecord -DomainName "evotec.pl","evotec.xyz"
    Test-DDEmailDkimRecord -DomainName "evotec.pl","evotec.xyz"
    Test-DDEmailDmarcRecord -DomainName "evotec.pl","evotec.xyz"
    Test-DDDnsNsRecord -DomainName "evotec.pl"
    Test-DDDnsSecStatus -DomainName "evotec.pl"
}

Metadata can be set globally:

Set-DDExportOptions -Title "Evotec - Q3 Portfolio Review" -Subject "Executive summary and remediation plan" -Category "Email Security" -Keywords "SPF,DKIM,DMARC" -Creator "Evotec"

Or per report:

Export-DDSecurityReport -ExportFormat Word -Title "Evotec - MX Review" -Subject "MX and transport policies"

• Most DNS-aware operations accept -DnsEndpoint to control resolution.
• Multi-resolver scenarios also support -DnsEndpoints and -MultiResolverStrategy.
• DNS propagation supports additional scope controls such as -Country, -Location, and -Take.
• WHOIS can compare current state to stored snapshots with -SnapshotPath and -Diff.
• Time-series features use -StorePath.
• Output formats include HTML, Word, Excel, PDF, Markdown, MarkdownHtml, and JSON, though support varies by cmdlet.

DNSBL providers can be customized at runtime. The built-in list can be extended, replaced, or filtered depending on how you want blacklist checks to behave.

Useful actions:

• Add providers
• Remove providers
• Clear the current list
• Load providers from JSON

C#:

var analysis = new DNSBLAnalysis();

analysis.AddDNSBL("dnsbl.example.com", comment: "custom");
analysis.RemoveDNSBL("dnsbl.example.com");
analysis.ClearDNSBL();
analysis.LoadDnsblConfig("DnsblProviders.json", overwriteExisting: true);

PowerShell:

Add-DnsblProvider -Domain "dnsbl.example.com" -Comment "custom"
Remove-DnsblProvider -Domain "dnsbl.example.com"
Clear-DnsblProvider
Import-DnsblConfig -Path "./DnsblProviders.json" -OverwriteExisting

Useful flags:

• -TreatAsDomain forces domain mode
• -TreatAsIp forces IP mode
• -MaxConcurrency hints concurrency to the resolver
• -BlacklistedOnly returns only listed results

Certificate analysis includes:

• KeyAlgorithm and KeySize
• WeakKey for keys under 2048 bits
• Sha1Signature
• IsSelfSigned
• PresentInCtLogs
• optional TLS negotiation details when capture is enabled
• optional revocation skipping via SkipRevocation

Combined website checks return a single summary object:

Test-Website -DomainName "evotec.xyz" | Select-Object Area,Check,Status,Summary,CertificateGrade,HttpGrade

DKIM analysis exposes indicators such as:

• WeakKey
• OldKey
• DeprecatedTags

SMTP TLS analysis stores the negotiated certificate and reports expiration details and chain validity for each server.

HTTP posture checks inspect common security headers including:

• Content-Security-Policy
• Referrer-Policy
• X-Frame-Options
• Permissions-Policy
• cross-origin policy headers

HttpAnalysis also tracks HSTS preload membership and computes a coarse grade from A through F.

DomainDetective/                Core analyzers, models, and protocol logic
DomainDetective.PowerShell/     Compiled PowerShell cmdlets
DomainDetective.CLI/            Spectre.Console CLI and wizard
DomainDetective.Reports/        Shared reporting abstractions and dispatch
DomainDetective.Reports.Html/   HTML composition reports
DomainDetective.Reports.Office/ Word and Excel reports
DomainDetective.Reports.Markdown/ Markdown and MarkdownHtml reports
DomainDetective.Reports.Pdf/    PDF report generator
DomainDetective.Example/        C# usage samples
Module/                         Importable module manifest, scripts, and PowerShell examples
Docs/                           Focused feature documentation
DomainDetective.Tests/          Core and PowerShell-facing tests
DomainDetective.CLI.Tests/      CLI tests

If you want runnable PowerShell examples, start in Module/Examples. If you want C# samples, start in DomainDetective.Example.

Restore, build, and run the main test suites:

dotnet restore DomainDetective.sln
dotnet build DomainDetective.sln
dotnet test DomainDetective.Tests/DomainDetective.Tests.csproj
dotnet test DomainDetective.CLI.Tests/DomainDetective.CLI.Tests.csproj

Run the PowerShell test harness:

pwsh ./Module/DomainDetective.Tests.ps1

NuGet packages:

pwsh ./Build/Build-NuGet.ps1 -Version 0.2.0

CLI publish artifacts:

pwsh ./Build/Publish-CLI.ps1 -Version 0.2.0

Run both through the shared build driver:

pwsh ./Build/Build-Project.ps1 -Version 0.2.0

Preview the plan without executing:

pwsh ./Build/Build-Project.ps1 -Plan

Outputs are staged under Artifacts/ProjectBuild:

• Artifacts/ProjectBuild/NuGet for .nupkg files
• Artifacts/ProjectBuild/CLI/<runtime> for published CLI folders
• Artifacts/ProjectBuild/CLI/*.zip for runtime archives when zipping is enabled

GitHub Actions currently validate:

• .NET 8 on Windows, Linux, and macOS
• .NET Framework 4.7.2 tests on Windows
• PowerShell 5.1 and 7+

Each analysis returns structured properties that map closely to the relevant RFCs or protocol expectations. That means the objects are meant to be usable in automation, not just rendered for humans.

Examples:

• SPF follows RFC 7208 lookup counting behavior and exposes resolved include and redirect chains.
• DKIM tracks minimum key expectations and sets WeakKey when RSA keys are too small.
• DMARC aligns policy, reporting, and enforcement posture.
• DANE and S/MIMEA follow their respective record semantics instead of just returning raw TXT strings.

WHOIS and summary data can also surface:

• expiration dates
• registrar lock state
• public suffix detection

C# example:

var health = new DomainHealthCheck();
await health.Verify("example.com");
var summary = health.BuildSummary();

Console.WriteLine($"Expires on: {summary.ExpiryDate}");
Console.WriteLine($"Registrar lock: {summary.RegistrarLocked}");
Console.WriteLine($"Is public suffix: {summary.IsPublicSuffix}");

For unified WHOIS and RDAP snapshots with structured drift:

Import-DDRegistrationSnapshot -DomainName "example.com" -StorePath .\Store
Get-DDRegistrationDrift -DomainName "example.com" -StorePath .\Store

C#:

using DnsClientX;

var hc = new DomainDetective.DomainHealthCheck();
hc.DnsEndpoints.Add(DnsEndpoint.CloudflareWireFormat);
hc.DnsEndpoints.Add(DnsEndpoint.Google);
hc.MultiResolverStrategy = DomainDetective.MultiResolverStrategy.FirstSuccess;

await hc.Verify("example.com", new[] { DomainDetective.HealthCheckType.SPF, DomainDetective.HealthCheckType.DNSSEC });

Console.WriteLine($"SPF present: {hc.SpfAnalysis.SpfRecordExists}; DS count: {hc.DnsSecAnalysis.DsRecords.Count}");

PowerShell:

Import-Module ./Module/DomainDetective.psd1 -Force

$domain = "evotec.pl"
$resolvers = @(
    [DnsClientX.DnsEndpoint]::CloudflareWireFormat,
    [DnsClientX.DnsEndpoint]::Google
)

Test-DDDomainOverallHealth -DomainName $domain -DnsEndpoints $resolvers -MultiResolverStrategy FirstSuccess -ExportFormat Word -ExportPath ".\Reports"

Start with these focused docs:

• Docs/DESIRED_STATE.MD
• Docs/CERTIFICATE_INVENTORY.MD
• Docs/DNS_PROPAGATION.MD
• Docs/CT_TIMELINE.MD
• Docs/DNS_INVENTORY.MD
• Docs/HTTP_POSTURE.MD
• Docs/IP_ENRICHMENT.MD
• Docs/SUBDOMAINS.MD
• Docs/EmailSmtpRules.md

If you just want one-off web lookups instead of local automation, common alternatives include:

• MXToolbox
• DNSChecker
• DNSStuff
• Dmarcian
• DMARC Analyzer
• DKIM Validator
• DKIM Core

See TODO.md for the current backlog and roadmap.

Issues, ideas, and pull requests are welcome. If you are not sure where to start, open an issue with the scenario you are trying to automate or the analysis gap you want covered.