Skip to content

Commit 7733da9

Browse files
oheimburgeroheimburger
authored
Merge pull request #1336 from oracle-devrel/jmsteur_email_security_protocol_checker
Jmsteur email security protocol checker
2 parents bfd31b4 + bbab5dd commit 7733da9

File tree

7 files changed

+888
-0
lines changed

7 files changed

+888
-0
lines changed

‎security/security-design/shared-assets/email-security-dns-check/LICENSE

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
Copyright (c) 2024 Oracle and/or its affiliates.
2+
3+
The Universal Permissive License (UPL), Version 1.0
4+
5+
Subject to the condition set forth below, permission is hereby granted to any
6+
person obtaining a copy of this software, associated documentation and/or data
7+
(collectively the "Software"), free of charge and under any and all copyright
8+
rights in the Software, and any and all patent rights owned or freely
9+
licensable by each licensor hereunder covering either (i) the unmodified
10+
Software as contributed to or provided by such licensor, or (ii) the Larger
11+
Works (as defined below), to deal in both
12+
13+
(a) the Software, and
14+
(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
15+
one is included with the Software (each a "Larger Work" to which the Software
16+
is contributed by such licensors),
17+
18+
without restriction, including without limitation the rights to copy, create
19+
derivative works of, display, perform, and distribute the Software and make,
20+
use, sell, offer for sale, import, export, have made, and have sold the
21+
Software and the Larger Work(s), and to sublicense the foregoing rights on
22+
either these or other terms.
23+
24+
This license is subject to the following condition:
25+
The above copyright notice and either this complete permission notice or at
26+
a minimum a reference to the UPL must be included in all copies or
27+
substantial portions of the Software.
28+
29+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
30+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
31+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
32+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
33+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
34+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
35+
SOFTWARE.

‎security/security-design/shared-assets/email-security-dns-check/README.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
## Purpose of the email security DNS check
2+
3+
Oracle requires that certain records are added to a customers DNS to allow Oracle's email delivery service to send emails on the customers behalf. This prevents the customers emails from being flagged as spoofed.
4+
5+
### Disclaimer
6+
7+
This asset uses a rest API to make it possible to show the geo-locations of the email servers in the SPF DNS records. This is done by making an HTTP request to the ip-api.com service.
8+
9+
The requests to ip-api.com are done in a anonymous way. The privacy policy at ip-api.com mentions that they do not track or analyse access or use in any manner. No cookies are placed during use.
10+
11+
To protect and rate-limit the API the network IP address of the client is stored in memory (RAM) for up to 1 minute.
12+
Any other information provided is discarded after the request is answered. Requests are not logged.
13+
The usage of the ip-api.com rest API is free for non-commercial use.
14+
15+
For more detail on the privacy policy, please visit [https://ip-api.com/privacy](https://ip-api.com/privacy).
16+
17+
This is not an official Oracle application and it is not supported by Oracle Support.
18+
19+
## Understanding SPF, DKIM, and DMARC
20+
21+
First a high level overview of the different protocols.
22+
23+
### SPF (Sender Policy Framework)
24+
25+
SPF is an email authentication protocol that allows a domain to specify which mail servers are authorized to send emails on its behalf. It works by publishing DNS records that define the authorized IP addresses. This helps prevent email spoofing.
26+
27+
### DKIM (DomainKeys Identified Mail)
28+
29+
DKIM is an email authentication method that adds a digital signature to email headers. This signature is linked to the domain and verified by the receiving server using a DKIM public key published in the sender’s DNS records.
30+
31+
### DMARC (Domain-based Message Authentication, Reporting, and Conformance)
32+
33+
DMARC builds on SPF and DKIM by specifying how the recipient should handle emails that fail SPF or DKIM checks. It provides reporting capabilities to monitor the domain’s email authentication.
34+
35+
### Email Authentication Flow with SPF, DKIM, and DMARC
36+
37+
Following diagram shows the flow through the different protocols:
38+
39+
```
40+
[ Sender's Email System ]
41+
|
42+
|-- Email sent with DKIM Signature
43+
|
44+
[ Internet ]
45+
|
46+
v
47+
[ Recipient's Email Server ]
48+
|
49+
|-- Step 1: SPF Check
50+
| - Is the sending IP authorized?
51+
|
52+
|-- Step 2: DKIM Verification
53+
| - Is the signature valid?
54+
|
55+
|-- Step 3: DMARC Policy Lookup
56+
| - What is the sender's DMARC policy?
57+
| - Do SPF/DKIM results align with the 'From' domain?
58+
|
59+
|-- Step 4: Apply DMARC Policy
60+
| - Deliver, Quarantine, or Reject
61+
v
62+
[ Recipient's Inbox or Spam Folder ]
63+
```
64+
65+
The following links provide documentation for diferent Oracle products referencing these settings for SPF, DKIM and DMARC.
66+
67+
### Resources
68+
69+
- [SPF settings in Email Delivery on OCI](https://docs.oracle.com/en-us/iaas/Content/Email/Tasks/configurespf.htm)
70+
- [DKIM settings in Email Delivery on OCI](https://docs.oracle.com/en-us/iaas/Content/Email/Tasks/configure-dkim-using-the-console.htm)
71+
- [Setting up an Email Domain with DKIM](https://docs.oracle.com/en-us/iaas/Content/Email/Tasks/managing_dkim-setup_email_domain_with_dkim.htm)
72+
- [Configuring Email Authentication Settings for SPF and DKIM on OCI IAM](https://docs.oracle.com/en-us/iaas/Content/Identity/notifications/configure-email-auth-spf-dkim.htm)
73+
- [Configure Email Security on Fusion Cloud Applications](https://docs.oracle.com/en/cloud/saas/applications-common/24d/facia/configure-email-security.html)

‎security/security-design/shared-assets/email-security-dns-check/files/email-security-dns-check/LICENSE

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
Copyright (c) 2024 Oracle and/or its affiliates.
2+
3+
The Universal Permissive License (UPL), Version 1.0
4+
5+
Subject to the condition set forth below, permission is hereby granted to any
6+
person obtaining a copy of this software, associated documentation and/or data
7+
(collectively the "Software"), free of charge and under any and all copyright
8+
rights in the Software, and any and all patent rights owned or freely
9+
licensable by each licensor hereunder covering either (i) the unmodified
10+
Software as contributed to or provided by such licensor, or (ii) the Larger
11+
Works (as defined below), to deal in both
12+
13+
(a) the Software, and
14+
(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
15+
one is included with the Software (each a "Larger Work" to which the Software
16+
is contributed by such licensors),
17+
18+
without restriction, including without limitation the rights to copy, create
19+
derivative works of, display, perform, and distribute the Software and make,
20+
use, sell, offer for sale, import, export, have made, and have sold the
21+
Software and the Larger Work(s), and to sublicense the foregoing rights on
22+
either these or other terms.
23+
24+
This license is subject to the following condition:
25+
The above copyright notice and either this complete permission notice or at
26+
a minimum a reference to the UPL must be included in all copies or
27+
substantial portions of the Software.
28+
29+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
30+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
31+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
32+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
33+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
34+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
35+
SOFTWARE.

‎security/security-design/shared-assets/email-security-dns-check/files/email-security-dns-check/README.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Email Security DNS Check
2+
3+
Owner: Jacco Steur
4+
5+
## When to use this asset?
6+
7+
This Python tool checks the email security settings of a domain by verifying its SPF, DKIM, and DMARC records. It extracts relevant information from a domain or an `.eml` file, performs validation, and outputs a summary of findings, including policies and IP addresses associated with SPF records. It can also analyze the alignment of sender information for SPF and DKIM, and resolve IP locations.
8+
9+
### Disclaimer
10+
11+
This asset covers the OCI platform as specified in the *CIS Oracle Cloud Infrastructure Foundations Benchmark*, only. Any workload provisioned in Databases, Compute VMs (running any Operating System), the Container Engine for Kubernetes, or in the VMware Solution is *out of scope* of the *OCI Security Health Check*.
12+
13+
This is not an official Oracle application and it is not supported
14+
by Oracle Support.
15+
16+
### Flags and Usage
17+
18+
- `-f --eml-file`: Path to the `.eml` file to analyze.
19+
- `-s --sender-domain`: Specify the sender domain directly.
20+
- `--selector`: DKIM selector for the sender domain, if known.
21+
- `--mx-selector`: DKIM selector for MX domains.
22+
- `-t --txt`: Dump all TXT records for the domain being checked.
23+
- `--resolve-spf`: Resolve all IP addresses in the SPF record and display their geolocation.
24+
25+
### Install the tool
26+
27+
After cloning the repository and cd into the right directory:
28+
29+
```
30+
security/security-design/shared-assets/email-security-dns-check
31+
```
32+
Run the following command in your terminal to initialize your pyhton environment:
33+
34+
```bash
35+
python3 -m venv .venv
36+
source .venv/bin/activate
37+
pip install -r requirements.txt
38+
```
39+
40+
### Usage examples
41+
42+
To check a domain’s SPF, DKIM, and DMARC settings:
43+
44+
```bash
45+
./email_security_check.sh -s oraclecloud.com
46+
```
47+
48+
For a reverse DNS check and geo location check of the mail server use the command as follows:
49+
50+
```bash
51+
./email_security_check.sh -s oraclecloud.com --resolve-spf
52+
```
53+
54+
If you know what the DKIM selector of the sending email domain is, use the tool as follows:
55+
56+
```bash
57+
./email_security_check.sh -s oraclecloud.com --selector selectoridcs-4
58+
```
59+
60+
If you have a email available from the sending email domain then this can be used to get the DKIM selector:
61+
62+
```bash
63+
./email_security_check.sh -f email.eml
64+
```

‎security/security-design/shared-assets/email-security-dns-check/files/email-security-dns-check/email_security_check.sh

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
#!/bin/bash
2+
###############################################################################
3+
# Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
4+
# This software is dual-licensed to you under the Universal Permissive License
5+
# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl.
6+
###############################################################################
7+
#
8+
# Author: Jacco Steur
9+
#
10+
##########################################################################
11+
# email_security_check.sh
12+
# Bash script to run the email security check Python script email_security_check.py
13+
##########################################################################
14+
15+
16+
##########################################################################
17+
# Check if the Python script exists
18+
##########################################################################
19+
SCRIPT_DIR="$(dirname "$0")"
20+
PYTHON_SCRIPT="${SCRIPT_DIR}/scripts/email_security_check.py"
21+
22+
if [ ! -f "$PYTHON_SCRIPT" ]; then
23+
echo "Python script 'email_security_check.py' not found in $SCRIPT_DIR."
24+
exit 1
25+
fi
26+
27+
##########################################################################
28+
# Function to display help message
29+
##########################################################################
30+
function usage() {
31+
echo "Usage: $0 [options]"
32+
echo ""
33+
echo "Options:"
34+
echo " -s, --sender-domain DOMAIN Sender domain (the domain where the email comes from)"
35+
echo " -f, --eml-file FILE Path to the .eml file to extract information from"
36+
echo " --selector SELECTOR DKIM selector for sender domain (if known)"
37+
echo " --mx-selector SELECTOR DKIM selector for MX domains (if known)"
38+
echo " -t, --txt Dump all TXT records for domains being checked"
39+
echo " --resolve-spf Resolve all IP addresses in SPF records and get their locations"
40+
echo " -h, --help Show this help message and exit"
41+
echo ""
42+
echo "Examples:"
43+
echo " $0 -s example.com"
44+
echo " $0 -s example.com --resolve-spf"
45+
echo " $0 -s example.com --selector selector1 -t"
46+
echo " $0 -f email_file.eml"
47+
exit 1
48+
}
49+
50+
# Parse command-line arguments
51+
SENDER_DOMAIN=""
52+
EML_FILE=""
53+
SELECTOR=""
54+
MX_SELECTOR=""
55+
TXT_FLAG=""
56+
RESOLVE_SPF_FLAG=""
57+
while [[ $# -gt 0 ]]; do
58+
case "$1" in
59+
-s|--sender-domain)
60+
SENDER_DOMAIN="$2"
61+
shift 2
62+
;;
63+
-f|--eml-file)
64+
EML_FILE="$2"
65+
shift 2
66+
;;
67+
--selector)
68+
SELECTOR="$2"
69+
shift 2
70+
;;
71+
--mx-selector)
72+
MX_SELECTOR="$2"
73+
shift 2
74+
;;
75+
-t|--txt)
76+
TXT_FLAG="--txt"
77+
shift
78+
;;
79+
--resolve-spf)
80+
RESOLVE_SPF_FLAG="--resolve-spf"
81+
shift
82+
;;
83+
-h|--help)
84+
usage
85+
;;
86+
*)
87+
echo "Unknown option: $1"
88+
usage
89+
;;
90+
esac
91+
done
92+
93+
# Ensure that either sender domain or .eml file is provided
94+
if [ -z "$SENDER_DOMAIN" ] && [ -z "$EML_FILE" ]; then
95+
echo "Error: Please provide a sender domain with -s or an .eml file with -f."
96+
usage
97+
fi
98+
99+
# Construct the command to run the Python script
100+
CMD="python3 \"$PYTHON_SCRIPT\""
101+
102+
if [ -n "$SENDER_DOMAIN" ]; then
103+
CMD="$CMD -s \"$SENDER_DOMAIN\""
104+
fi
105+
106+
if [ -n "$EML_FILE" ]; then
107+
CMD="$CMD -f \"$EML_FILE\""
108+
fi
109+
110+
if [ -n "$SELECTOR" ]; then
111+
CMD="$CMD --selector \"$SELECTOR\""
112+
fi
113+
114+
if [ -n "$MX_SELECTOR" ]; then
115+
CMD="$CMD --mx-selector \"$MX_SELECTOR\""
116+
fi
117+
118+
if [ -n "$TXT_FLAG" ]; then
119+
CMD="$CMD $TXT_FLAG"
120+
fi
121+
122+
if [ -n "$RESOLVE_SPF_FLAG" ]; then
123+
CMD="$CMD $RESOLVE_SPF_FLAG"
124+
fi
125+
126+
# Execute the command
127+
eval $CMD

‎security/security-design/shared-assets/email-security-dns-check/files/email-security-dns-check/requirements.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
dnspython
2+
tabulate
3+
pyspf
4+
dkimpy
5+
geoip2

0 commit comments

Comments
 (0)