# Trustworthy Mail #
[](https://pypi.org/project/trustymail/)
[](https://github.com/cisagov/trustymail/actions)
[](https://github.com/cisagov/trustymail/actions/workflows/codeql-analysis.yml)
[](https://coveralls.io/github/cisagov/trustymail?branch=develop)
[](https://snyk.io/test/github/cisagov/trustymail)
`trustymail` is a tool that evaluates SPF/DMARC records set in a
domain's DNS. It also checks the mail servers listed in a domain's MX
records for STARTTLS support. It saves its results to CSV or JSON.
## Getting started ##
`trustymail` requires **Python 3.6+**. Python 2 is not supported.
### Local installation ###
`trustymail` can be installed directly via pip:
```console
pip install trustymail
```
It can then be run directly:
```console
trustymail [options] example.com
```
or
```console
python3 -m trustymail [options] example.com
```
### Using Docker (optional) ###
```console
./run [opts]
```
`opts` are the same arguments that would get passed to `trustymail`.
### Usage and examples ###
```console
trustymail [options] INPUT
trustymail dhs.gov
trustymail --output=homeland.csv --debug cisa.gov dhs.gov us-cert.gov usss.gov
trustymail agencies.csv
```
Note: if INPUT ends with `.csv`, domains will be read from CSV. CSV
output will always be written to disk, defaulting to `results.csv`.
#### Options ####
```console
-h --help Show this message.
-o --output=OUTFILE Name of output file. (Default results)
-t --timeout=TIMEOUT The DNS lookup timeout in seconds. (Default is 5.)
--smtp-timeout=TIMEOUT The SMTP connection timeout in seconds. (Default is 5.)
--smtp-localhost=HOSTNAME The hostname to use when connecting to SMTP
servers. (Default is the FQDN of the host from
which trustymail is being run.)
--smtp-ports=PORTS A comma-delimited list of ports at which to look
for SMTP servers. (Default is '25,465,587'.)
--no-smtp-cache Do not cache SMTP results during the run. This
may results in slower scans due to testing the
same mail servers multiple times.
--mx Only check MX records.
--starttls Only check MX records and STARTTLS support.
(Implies --mx.)
--spf Only check SPF records.
--dmarc Only check DMARC records.
--json Output is in JSON format. (Default is CSV.)
--debug Output should include more verbose logging.
--dns=HOSTNAMES A comma-delimited list of DNS servers to query
against. For example, if you want to use
Google's DNS then you would use the
value --dns-hostnames='8.8.8.8,8.8.4.4'. By
default the DNS configuration of the host OS
(/etc/resolv.conf) is used. Note that
the host's DNS configuration is not used at all
if this option is used.
--psl-filename=FILENAME The name of the file where the public suffix list
(PSL) cache will be saved. If set to the name of
an existing file then that file will be used as
the PSL. If not present then the PSL cache will
be saved to a file in the current directory called
public_suffix_list.dat.
--psl-read-only If present, then the public suffix list (PSL)
cache will be read but never overwritten. This
is useful when running in AWS Lambda, for
instance, where the local filesystem is read-only.
```
## What's checked? ##
For a given domain, MX records, SPF records (TXT), DMARC (TXT, at
`_dmarc.<domain>`), and support for STARTTLS are checked. Resource records can
also be checked for DNSSEC if the resolver used is DNSSEC-aware.
The following values are returned in `results.csv`:
### Domain and redirect info ###
- `Domain` - The domain you're scanning!
- `Base Domain` - The base domain of `Domain`. For example, for a
Domain of `sub.example.gov`, the Base Domain will be
`example.gov`. Usually this is the second-level domain, but
`trustymail` will download and factor in the [Public Suffix
List](https://publicsuffix.org) when calculating the base domain.
- `Live` - The domain is actually published in the DNS.
### Mail sending ###
- `MX Record` - If an MX record was found that contains at least a
single mail server.
- `MX Record DNSSEC` - A boolean value indicating whether or not the
DNS record is protected by DNSSEC.
- `Mail Servers` - The list of hosts found in the MX record.
- `Mail Server Ports Tested` - A list of the ports tested for SMTP and
STARTTLS support.
- `Domain Supports SMTP` - True if and only if **any** mail servers
specified in a MX record associated with the domain supports SMTP.
- `Domain Supports SMTP Results` - A list of the mail server and port
combinations that support SMTP.
- `Domain Supports STARTTLS` - True if and only if **all** mail
servers that support SMTP also support STARTTLS.
- `Domain Supports STARTTLS Results` - A list of the mail server and
port combinations that support STARTTLS.
### Sender Policy Framework (SPF) ###
- `SPF Record` - Whether or not a SPF record was found.
- `SPF Record DNSSEC` - A boolean value indicating whether or not the
DNS record is protected by DNSSEC.
- `Valid SPF` - Whether the SPF record found is syntactically correct,
per RFC 4408.
- `SPF Results` - The textual representation of any SPF record found
for the domain.
### Domain-based Message Authentication, Reporting, and Conformance (DMARC) ###
- `DMARC Record` - True/False whether or not a DMARC record was found.
- `DMARC Record DNSSEC` - A boolean value indicating whether or not
the DNS record is protected by DNSSEC.
- `Valid DMARC` - Whether the DMARC record found is syntactically
correct.
- `DMARC Results` - The DMARC record that was discovered when querying
DNS.
- `DMARC Record on Base Domain`, `DMARC Record on Base Domain DNSSEC`,
`Valid DMARC Record on Base Domain`, `DMARC Results on Base
Domain` - Same definition as above, but returns the result for the
Base Domain. This is important in DMARC because if there isn't a
DMARC record at the domain, the base domain (or "Organizational
Domain", per [RFC
7489](https://tools.ietf.org/html/rfc7489#section-6.6.3)), is
checked and applied.
- `DMARC Policy` - An adjudication, based on any policies found in
`DMARC Results` and `DMARC Results on Base Domain`, of the relevant
DMARC policy that applies.
- `DMARC Subdomain Policy` - An adjudication, based on any policies
found in `DMARC Results` and `DMARC Results on Base Domain`, of the
relevant DMARC subdomain policy that applies.
- `DMARC Policy Percentage` - The percentage of mail that should be
subjected to the `DMARC Policy` according to the `DMARC Results`.
- `DMARC Aggregate Report URIs` - A list of the DMARC aggregate report
URIs specified by the domain.
- `DMARC Forensic Report URIs` - A list of the DMARC forensic report
URIs specified by the domain.
- `DMARC Has Aggregate Report URI` - A boolean value that indicates if
`DMARC Results` included `rua` URIs that tell recipients where to
send DMARC aggregate reports.
- `DMARC Has Forensic Report URI` - A boolean value that indicates if
`DMARC Results` included `ruf` URIs that tell recipients where to
send DMARC forensic reports.
- `DMARC Reporting Address Acceptance Error` - A boolean value that is
True if one or more of the domains listed in the aggregate and
forensic report URIs does not indicate that it accepts DMARC reports
from the domain being tested.
### Everything else ###
- `Syntax Errors` - A list of syntax errors that were encountered when
analyzing SPF records.
- `Debug Info` - A list of any other warnings or errors encountered,
such as DNS failures. These can be helpful when determining how
`trustymail` reached its conclusions, and are indispensible for bug
reports.
## Contributing ##
We welcome contributions! Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for
details.
## License ##
This project is in the worldwide [public domain](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://www.cisa.gov/cybersecurity",
"name": "trustymail",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "email authentication STARTTLS",
"author": "Cybersecurity and Infrastructure Security Agency",
"author_email": "github@cisa.dhs.gov",
"download_url": "https://files.pythonhosted.org/packages/77/83/cab3d37e272832b2ed39ee9da5b9575a7909df29a8b1dab6c53fe1508ff0/trustymail-0.8.1.tar.gz",
"platform": null,
"description": "# Trustworthy Mail #\n\n[](https://pypi.org/project/trustymail/)\n[](https://github.com/cisagov/trustymail/actions)\n[](https://github.com/cisagov/trustymail/actions/workflows/codeql-analysis.yml)\n[](https://coveralls.io/github/cisagov/trustymail?branch=develop)\n[](https://snyk.io/test/github/cisagov/trustymail)\n\n`trustymail` is a tool that evaluates SPF/DMARC records set in a\ndomain's DNS. It also checks the mail servers listed in a domain's MX\nrecords for STARTTLS support. It saves its results to CSV or JSON.\n\n## Getting started ##\n\n`trustymail` requires **Python 3.6+**. Python 2 is not supported.\n\n### Local installation ###\n\n`trustymail` can be installed directly via pip:\n\n```console\npip install trustymail\n```\n\nIt can then be run directly:\n\n```console\ntrustymail [options] example.com\n```\n\nor\n\n```console\npython3 -m trustymail [options] example.com\n```\n\n### Using Docker (optional) ###\n\n```console\n./run [opts]\n```\n\n`opts` are the same arguments that would get passed to `trustymail`.\n\n### Usage and examples ###\n\n```console\ntrustymail [options] INPUT\n\ntrustymail dhs.gov\ntrustymail --output=homeland.csv --debug cisa.gov dhs.gov us-cert.gov usss.gov\ntrustymail agencies.csv\n```\n\nNote: if INPUT ends with `.csv`, domains will be read from CSV. CSV\noutput will always be written to disk, defaulting to `results.csv`.\n\n#### Options ####\n\n```console\n -h --help Show this message.\n -o --output=OUTFILE Name of output file. (Default results)\n -t --timeout=TIMEOUT The DNS lookup timeout in seconds. (Default is 5.)\n --smtp-timeout=TIMEOUT The SMTP connection timeout in seconds. (Default is 5.)\n --smtp-localhost=HOSTNAME The hostname to use when connecting to SMTP\n servers. (Default is the FQDN of the host from\n which trustymail is being run.)\n --smtp-ports=PORTS A comma-delimited list of ports at which to look\n for SMTP servers. (Default is '25,465,587'.)\n --no-smtp-cache Do not cache SMTP results during the run. This\n may results in slower scans due to testing the\n same mail servers multiple times.\n --mx Only check MX records.\n --starttls Only check MX records and STARTTLS support.\n (Implies --mx.)\n --spf Only check SPF records.\n --dmarc Only check DMARC records.\n --json Output is in JSON format. (Default is CSV.)\n --debug Output should include more verbose logging.\n --dns=HOSTNAMES A comma-delimited list of DNS servers to query\n against. For example, if you want to use\n Google's DNS then you would use the\n value --dns-hostnames='8.8.8.8,8.8.4.4'. By\n default the DNS configuration of the host OS\n (/etc/resolv.conf) is used. Note that\n the host's DNS configuration is not used at all\n if this option is used.\n --psl-filename=FILENAME The name of the file where the public suffix list\n (PSL) cache will be saved. If set to the name of\n an existing file then that file will be used as\n the PSL. If not present then the PSL cache will\n be saved to a file in the current directory called\n public_suffix_list.dat.\n --psl-read-only If present, then the public suffix list (PSL)\n cache will be read but never overwritten. This\n is useful when running in AWS Lambda, for\n instance, where the local filesystem is read-only.\n```\n\n## What's checked? ##\n\nFor a given domain, MX records, SPF records (TXT), DMARC (TXT, at\n`_dmarc.<domain>`), and support for STARTTLS are checked. Resource records can\nalso be checked for DNSSEC if the resolver used is DNSSEC-aware.\n\nThe following values are returned in `results.csv`:\n\n### Domain and redirect info ###\n\n- `Domain` - The domain you're scanning!\n- `Base Domain` - The base domain of `Domain`. For example, for a\n Domain of `sub.example.gov`, the Base Domain will be\n `example.gov`. Usually this is the second-level domain, but\n `trustymail` will download and factor in the [Public Suffix\n List](https://publicsuffix.org) when calculating the base domain.\n- `Live` - The domain is actually published in the DNS.\n\n### Mail sending ###\n\n- `MX Record` - If an MX record was found that contains at least a\n single mail server.\n- `MX Record DNSSEC` - A boolean value indicating whether or not the\n DNS record is protected by DNSSEC.\n- `Mail Servers` - The list of hosts found in the MX record.\n- `Mail Server Ports Tested` - A list of the ports tested for SMTP and\n STARTTLS support.\n- `Domain Supports SMTP` - True if and only if **any** mail servers\n specified in a MX record associated with the domain supports SMTP.\n- `Domain Supports SMTP Results` - A list of the mail server and port\n combinations that support SMTP.\n- `Domain Supports STARTTLS` - True if and only if **all** mail\n servers that support SMTP also support STARTTLS.\n- `Domain Supports STARTTLS Results` - A list of the mail server and\n port combinations that support STARTTLS.\n\n### Sender Policy Framework (SPF) ###\n\n- `SPF Record` - Whether or not a SPF record was found.\n- `SPF Record DNSSEC` - A boolean value indicating whether or not the\n DNS record is protected by DNSSEC.\n- `Valid SPF` - Whether the SPF record found is syntactically correct,\n per RFC 4408.\n- `SPF Results` - The textual representation of any SPF record found\n for the domain.\n\n### Domain-based Message Authentication, Reporting, and Conformance (DMARC) ###\n\n- `DMARC Record` - True/False whether or not a DMARC record was found.\n- `DMARC Record DNSSEC` - A boolean value indicating whether or not\n the DNS record is protected by DNSSEC.\n- `Valid DMARC` - Whether the DMARC record found is syntactically\n correct.\n- `DMARC Results` - The DMARC record that was discovered when querying\n DNS.\n- `DMARC Record on Base Domain`, `DMARC Record on Base Domain DNSSEC`,\n `Valid DMARC Record on Base Domain`, `DMARC Results on Base\n Domain` - Same definition as above, but returns the result for the\n Base Domain. This is important in DMARC because if there isn't a\n DMARC record at the domain, the base domain (or \"Organizational\n Domain\", per [RFC\n 7489](https://tools.ietf.org/html/rfc7489#section-6.6.3)), is\n checked and applied.\n- `DMARC Policy` - An adjudication, based on any policies found in\n `DMARC Results` and `DMARC Results on Base Domain`, of the relevant\n DMARC policy that applies.\n- `DMARC Subdomain Policy` - An adjudication, based on any policies\n found in `DMARC Results` and `DMARC Results on Base Domain`, of the\n relevant DMARC subdomain policy that applies.\n- `DMARC Policy Percentage` - The percentage of mail that should be\n subjected to the `DMARC Policy` according to the `DMARC Results`.\n- `DMARC Aggregate Report URIs` - A list of the DMARC aggregate report\n URIs specified by the domain.\n- `DMARC Forensic Report URIs` - A list of the DMARC forensic report\n URIs specified by the domain.\n- `DMARC Has Aggregate Report URI` - A boolean value that indicates if\n `DMARC Results` included `rua` URIs that tell recipients where to\n send DMARC aggregate reports.\n- `DMARC Has Forensic Report URI` - A boolean value that indicates if\n `DMARC Results` included `ruf` URIs that tell recipients where to\n send DMARC forensic reports.\n- `DMARC Reporting Address Acceptance Error` - A boolean value that is\n True if one or more of the domains listed in the aggregate and\n forensic report URIs does not indicate that it accepts DMARC reports\n from the domain being tested.\n\n### Everything else ###\n\n- `Syntax Errors` - A list of syntax errors that were encountered when\n analyzing SPF records.\n- `Debug Info` - A list of any other warnings or errors encountered,\n such as DNS failures. These can be helpful when determining how\n `trustymail` reached its conclusions, and are indispensible for bug\n reports.\n\n## Contributing ##\n\nWe welcome contributions! Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for\ndetails.\n\n## License ##\n\nThis project is in the worldwide [public domain](LICENSE).\n",
"bugtrack_url": null,
"license": "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
"summary": "Scan domains and return data based on trustworthy email best practices",
"version": "0.8.1",
"split_keywords": [
"email",
"authentication",
"starttls"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b2fa48dd87739c3517137cff25a3369fb6825def4a8d1663c49b69d9bd27167",
"md5": "c37ce72863d8f6eccb3ef90f77f53b72",
"sha256": "25ccf056db063a568dcebdaee8f86b59391dc75dfe5ee485f2e6b7673ed08dc8"
},
"downloads": -1,
"filename": "trustymail-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c37ce72863d8f6eccb3ef90f77f53b72",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 24686,
"upload_time": "2023-01-30T18:36:45",
"upload_time_iso_8601": "2023-01-30T18:36:45.494676Z",
"url": "https://files.pythonhosted.org/packages/8b/2f/a48dd87739c3517137cff25a3369fb6825def4a8d1663c49b69d9bd27167/trustymail-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7783cab3d37e272832b2ed39ee9da5b9575a7909df29a8b1dab6c53fe1508ff0",
"md5": "6ad6802b5739813870fa143eae5a0bf1",
"sha256": "91ac1d80a82924e2859b7c413e9a4e689417805ec5a217be18f198731965c2d8"
},
"downloads": -1,
"filename": "trustymail-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "6ad6802b5739813870fa143eae5a0bf1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 26282,
"upload_time": "2023-01-30T18:36:47",
"upload_time_iso_8601": "2023-01-30T18:36:47.089745Z",
"url": "https://files.pythonhosted.org/packages/77/83/cab3d37e272832b2ed39ee9da5b9575a7909df29a8b1dab6c53fe1508ff0/trustymail-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-30 18:36:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "trustymail"
}
JSON