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
 
    SPF records can also be tested recursively, to see how many DNS lookups are
    required to evaluate them. If more than ten additional DNS lookups are re-
    quired, parsers may choose to terminate processing and return a PermError.
    There are two ways to do this:
 
    PS C:\> Test-MailPolicy lucernepublishing.com -CountSpfDnsLookups
    PS C:\> Test-SpfRecord lucernepublishing.com -CountDnsLookups
 
    PROTIP: You can use the alias `-Recurse` instead.
 
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.
 
Disabling DNSSEC Validation
    You may disable most cmdlets' built-in DNSSEC verification by specifying the
    `-DisableDnssecValidation` (alias: `-CD`). Queries to the upstream resolver
    will request that DNSSEC checking be disabled; thus, DNSSEC validation of
    resource records will not occur, nor will you be informed of unauthenticated
    denial of existence of DNS records.
     
    It is best practice that all zones, records, and delegations be signed with
    DNSSEC. Using this switch is NOT RECOMMENDED for production use and should
    only be used for diagnostic and troubleshooting purposes only!
 
    Note that DANE requires DNSSEC. Using this switch with `Test-DaneRecord`
    will print a warning, and DNSSEC validation will occur normally
 
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 to make sure servers have both A and AAAA records,
      but it does not check to see if they are both working.
    - This module can test SPF records, but it does not know if you're missing
      an `include:` for some third-party service.
    - 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-IPVersions
 
    - 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, Sender ID, DKIM, ADSP, DMARC, BIMI, DNS, DNSSEC, DANE, TLSA,
    TXT, IDN, MTA-STS, TLSRPT, IPv4, IPv6, StartTLS, SSL, TLS, mail, email,
    Exchange Online, Google Workspace, Office 365.