Jmsteur email security protocol checker

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

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

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

@@ -0,0 +1,72 @@
+## Purpose of the email security DNS check
+
+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. 
+
+### Disclaimer
+
+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.
+
+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.
+
+To protect and rate-limit the API the network IP address of the client is stored in memory (RAM) for up to 1 minute.
+Any other information provided is discarded after the request is answered. Requests are not logged.
+
+For more detail on the privacy policy, please visit [https://ip-api.com/privacy](https://ip-api.com/privacy).
+
+This is not an official Oracle application and it is not supported by Oracle Support.
+
+## Understanding SPF, DKIM, and DMARC
+
+First a high level overview of the different protocols.
+
+### SPF (Sender Policy Framework)
+
+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.
+
+### DKIM (DomainKeys Identified Mail)
+
+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.
+
+### DMARC (Domain-based Message Authentication, Reporting, and Conformance)
+
+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.
+
+### Email Authentication Flow with SPF, DKIM, and DMARC
+
+Following diagram shows the flow through the different protocols:
+
+```
+[ Sender's Email System ]
+    |
+    |-- Email sent with DKIM Signature
+    |
+[ Internet ]
+    |
+    v
+[ Recipient's Email Server ]
+    |
+    |-- Step 1: SPF Check
+    |     - Is the sending IP authorized?
+    |
+    |-- Step 2: DKIM Verification
+    |     - Is the signature valid?
+    |
+    |-- Step 3: DMARC Policy Lookup
+    |     - What is the sender's DMARC policy?
+    |     - Do SPF/DKIM results align with the 'From' domain?
+    |
+    |-- Step 4: Apply DMARC Policy
+    |     - Deliver, Quarantine, or Reject
+    v
+[ Recipient's Inbox or Spam Folder ]
+```
+
+The following links provide documentation for diferent Oracle products referencing these settings for SPF, DKIM and DMARC. 
+
+### Resources
+
+- [SPF settings in Email Delivery on OCI](https://docs.oracle.com/en-us/iaas/Content/Email/Tasks/configurespf.htm)
+- [DKIM settings in Email Delivery on OCI](https://docs.oracle.com/en-us/iaas/Content/Email/Tasks/configure-dkim-using-the-console.htm)
+- [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)
+- [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)
+- [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

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

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

@@ -0,0 +1,64 @@
+# Email Security DNS Check
+
+Owner: Jacco Steur
+
+## When to use this asset?
+
+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.
+
+### Disclaimer
+
+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*.
+
+This is not an official Oracle application and it is not supported
+by Oracle Support.
+
+### Flags and Usage
+
+- `-f --eml-file`: Path to the `.eml` file to analyze.
+- `-s --sender-domain`: Specify the sender domain directly.
+- `--selector`: DKIM selector for the sender domain, if known.
+- `--mx-selector`: DKIM selector for MX domains.
+- `-t --txt`: Dump all TXT records for the domain being checked.
+- `--resolve-spf`: Resolve all IP addresses in the SPF record and display their geolocation.
+
+### Install the tool
+
+After cloning the repository and cd into the right directory:
+
+```
+security/security-design/shared-assets/email-security-dns-check
+```
+Run the following command in your terminal to initialize your pyhton environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Usage examples 
+
+To check a domain’s SPF, DKIM, and DMARC settings:
+
+```bash
+./email_security_check.sh -s oraclecloud.com
+```
+
+For a reverse DNS check and geo location check of the mail server use the command as follows:
+
+```bash
+./email_security_check.sh -s oraclecloud.com --resolve-spf
+```
+
+If you know what the DKIM selector of the sending email domain is, use the tool as follows:
+
+```bash
+./email_security_check.sh -s oraclecloud.com --selector selectoridcs-4 
+```
+
+If you have a email available from the sending email domain then this can be used to get the DKIM selector:
+
+```bash
+./email_security_check.sh -f email.eml 
+```

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

@@ -0,0 +1,127 @@
+#!/bin/bash
+###############################################################################
+# Copyright (c) 2024, Oracle and/or its affiliates.  All rights reserved.
+# This software is dual-licensed to you under the Universal Permissive License
+# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl.
+###############################################################################
+#
+# Author: Jacco Steur
+#
+##########################################################################
+# email_security_check.sh
+# Bash script to run the email security check Python script email_security_check.py
+##########################################################################
+
+
+##########################################################################
+# Check if the Python script exists
+##########################################################################
+SCRIPT_DIR="$(dirname "$0")"
+PYTHON_SCRIPT="${SCRIPT_DIR}/scripts/email_security_check.py"
+
+if [ ! -f "$PYTHON_SCRIPT" ]; then
+    echo "Python script 'email_security_check.py' not found in $SCRIPT_DIR."
+    exit 1
+fi
+
+##########################################################################
+# Function to display help message
+##########################################################################
+function usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  -s, --sender-domain DOMAIN     Sender domain (the domain where the email comes from)"
+    echo "  -f, --eml-file FILE            Path to the .eml file to extract information from"
+    echo "      --selector SELECTOR        DKIM selector for sender domain (if known)"
+    echo "      --mx-selector SELECTOR     DKIM selector for MX domains (if known)"
+    echo "  -t, --txt                      Dump all TXT records for domains being checked"
+    echo "      --resolve-spf              Resolve all IP addresses in SPF records and get their locations"
+    echo "  -h, --help                     Show this help message and exit"
+    echo ""
+    echo "Examples:"
+    echo "  $0 -s example.com"
+    echo "  $0 -s example.com --resolve-spf"
+    echo "  $0 -s example.com --selector selector1 -t"
+    echo "  $0 -f email_file.eml"
+    exit 1
+}
+
+# Parse command-line arguments
+SENDER_DOMAIN=""
+EML_FILE=""
+SELECTOR=""
+MX_SELECTOR=""
+TXT_FLAG=""
+RESOLVE_SPF_FLAG=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -s|--sender-domain)
+            SENDER_DOMAIN="$2"
+            shift 2
+            ;;
+        -f|--eml-file)
+            EML_FILE="$2"
+            shift 2
+            ;;
+        --selector)
+            SELECTOR="$2"
+            shift 2
+            ;;
+        --mx-selector)
+            MX_SELECTOR="$2"
+            shift 2
+            ;;
+        -t|--txt)
+            TXT_FLAG="--txt"
+            shift
+            ;;
+        --resolve-spf)
+            RESOLVE_SPF_FLAG="--resolve-spf"
+            shift
+            ;;
+        -h|--help)
+            usage
+            ;;
+        *)
+            echo "Unknown option: $1"
+            usage
+            ;;
+    esac
+done
+
+# Ensure that either sender domain or .eml file is provided
+if [ -z "$SENDER_DOMAIN" ] && [ -z "$EML_FILE" ]; then
+    echo "Error: Please provide a sender domain with -s or an .eml file with -f."
+    usage
+fi
+
+# Construct the command to run the Python script
+CMD="python3 \"$PYTHON_SCRIPT\""
+
+if [ -n "$SENDER_DOMAIN" ]; then
+    CMD="$CMD -s \"$SENDER_DOMAIN\""
+fi
+
+if [ -n "$EML_FILE" ]; then
+    CMD="$CMD -f \"$EML_FILE\""
+fi
+
+if [ -n "$SELECTOR" ]; then
+    CMD="$CMD --selector \"$SELECTOR\""
+fi
+
+if [ -n "$MX_SELECTOR" ]; then
+    CMD="$CMD --mx-selector \"$MX_SELECTOR\""
+fi
+
+if [ -n "$TXT_FLAG" ]; then
+    CMD="$CMD $TXT_FLAG"
+fi
+
+if [ -n "$RESOLVE_SPF_FLAG" ]; then
+    CMD="$CMD $RESOLVE_SPF_FLAG"
+fi
+
+# Execute the command
+eval $CMD

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

@@ -0,0 +1,5 @@
+dnspython
+tabulate
+pyspf
+dkimpy
+geoip2