en-US/about_MailPolicyExplainer.help.txt
|
TOPIC
about_MailPolicyExplainer SHORT DESCRIPTION A PowerShell module to fetch and analyze a domain's mail-related DNS records. LONG DESCRIPTION MailPolicyExplainer is just that: a PowerShell module that will retrieve all of a domain's email-related DNS records, and show them to the user. However, unlike a simple call to `Resolve-DnsName`, this module will actually analyze them and show you what they mean, rather than just what they are. This module supports MX, SPF, DKIM ADSP, DMARC, DANE, MTA-STS, and SMTP TLS Reporting; as well as evaluating whether or not records are signed with DNSSEC. In addition, if you provide names of selectors, DKIM and BIMI selector records are also evaluated. EXAMPLES Most people using this module will want to use the `Test-MailPolicy` cmdlet, which runs every single test in order. Though it may not be obvious which DKIM and BIMI selector names exist (save for email services like Exchange Online who use well-known DKIM selector names -- selector1 and selector2), the `-DkimSelectorsToCheck` and `-BimiSelectorsToCheck` can be used to test known selectors. In its simplest form, `Test-MailPolicy` will review almost every DNS record available. PS C:\> Test-MailPolicy contoso.com Exchange Online always uses DKIM selectors "selector1" and "selector2". If a domain doesn't use any other email sending platforms (such as Constant Contact), you can test any Office 365 customer with this command: PS C:\> Test-MailPolicy fabrikam.com -DkimSelectorsToCheck "selector1","selector2" But what if they do use something like Constant Contact? Assuming the DKIM selector name is known: PS C:\> Test-MailPolicy woodgrovebank.com -DkimSelectorsToCheck "selector1","selector2","constantcontact" Note that sometimes emails can come from subdomains, and those subdomains will have their own DNS records. You will need to run this cmdlet once per domain. PS C:\> Test-MailPolicy tailspintoys.com -DkimSelectorsToCheck "selector1","selector2" PS C:\> Test-MailPolicy shop.tailspintoys.com -DkimSelectorsToCheck "shopify" Or, if you only want to test one aspect of email, you can test items individually. For example, if yu're working on MTA-STS, you can skip all the other checks. PS C:\> Test-MtaStsPolicy adatum.com NOTE No command output is sent to the pipeline. All output is sent to the output stream, where it can be read by humans. However, the output stream can be redirected to a text file. TROUBLESHOOTING NOTE Help All cmdlets provide detailed help, available using the PowerShell `Get-Help` command. In addition, several relevant RFCs are available as conceptual help topics in case you'd like to learn more about the standards that are being tested. Limitations While this module does its best to test the correctness of DNS records, it cannot ensure the complete validity of everything. For example: - This module can test MX records, but not whether or not A/AAAA records are in place for those names. - This module can test SPF records, but it does not evaluate whether or not a PermError occurs, or if a required token is missing. - This module can test DKIM selectors, but it cannot test whether outgoing messages are being signed. - This module can test DANE records, but not whether or not the records are correct for an MX lookup. - This module can test BIMI records, but not whether the linked SVG image is valid, whether or not the client trusts the assertion, nor if outgoing emails have the appropriate BIMI headers. - This module cannot test internal DNS zones (i.e., ones that are not re- solvable over the public Internet). - This module can look up DMARC or TLSRPT reporting addresses, but cannot check to see if reports can be successfully submitted. Some of these limitations (such as testing DANE records) may be addressed in future versions of the module. Privacy As the built-in `Resolve-DnsName` cmdlet doesn't do everything that we need it to do (and because it's conspicuously absent on non-Windows versions of PowerShell), these cmdlets need to rely on an outside DNS resolving service. After testing some options, the only reliable cross-platform option was to use Google's Public DNS API. DNSSEC is always attempted, but left for the resolver to verify. Some people may have privacy concerns about sending random DNS queries to Google. Until Microsoft ports their DnsClient module to other platforms, and ensures that it can look up any type of DNS record, we are stuck using a third-party resource. However, future versions of this module may introduce support for using other public DNS APIs, or switching to proper DNS-over-HTTPS so that user-provided servers can be used. To troubleshoot DNS lookups, a cmdlet, Invoke-GooglePublicDnsApi, is made available. However, it is not intended for public use, and is subject to change or removal at any time. While the domain owner has no way to know which DNS lookups you and this module are doing, note that the MTA-STS does connect to the company's web server in order to retrieve the MTA-STS policy file. A single HTTP GET request will be made from your current IP address to the well-known location https://mta-sts.contoso.com/.well-known/mta-sts.txt (assuming you're testing against contoso.com). Bug Reporting and Feature Requests As this module relies on parsing DNS records that are supposed to follow a strict set of rules, it is unlikely that you will run into any issues. Should you encounter problems, though, you are encouraged to file issues on GitHub. SEE ALSO - Test-MailPolicy - Test-MXRecord - about_SMTP - about_MXRecords - about_NullMXRecords - about_IDNEmailAuthentication - Test-BimiSelector - about_BIMI - Test-DaneRecord - about_DANERecords - about_DANERecordsAcronyms - about_DANERecordsUsage - Test-DkimSelector - Test-AdspRecord - about_DKIM - about_DKIMADSP - about_DKIMRSAKeyUpdates - about_DKIMEd25519 - Test-DmarcRecord - about_DMARC - Test-MtaStsPolicy - about_MTA-STS - Test-SmtpTlsReportingPolicy - about_SMTPTLSReporting - Test-SpfRecord - about_SPF KEYWORDS SMTP, MX, SPF, DKIM, ADSP, DMARC, BIMI, DNS, DNSSEC, DANE, TLSA, TXT, IDN, MTA-STS, mail, email, Exchange Online, Google Workspace, Office 365. |