-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: merge experimental branch for total code refactor and new funct…
…ionality This merge pull request includes a comprehensive refactor of the codebase, introducing new features and improvements.
- Loading branch information
Showing
10 changed files
with
516 additions
and
989 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,2 @@ | ||
.idea | ||
.idea | ||
config/config.ini |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,56 +1,75 @@ | ||
# DMARC Report Analyzer | ||
|
||
## Introduction | ||
|
||
Welcome to the DMARC Report Analyzer! | ||
This little script will sift through your DMARC reports like a prospector panning for gold. | ||
|
||
It's going to parse, extract, and analyze those reports, and when it's all done, it'll give you a shiny CSV file. | ||
|
||
So, grab a drink, sit back, and let this script do the heavy lifting. | ||
|
||
## What It Does | ||
|
||
This script will: | ||
1. **Scan your directory** for any DMARC report files. It can handle `.xml`, `.gz`, and `.zip` files, because we like to cover all bases. | ||
2. **Parse the reports** and extract the important stuff. Think of it like Antonio in foreign land looking for where to drink Guinness. | ||
3. **Analyze the data** to find out which emails failed SPF, DKIM, or both. | ||
4. **Check blacklists** for IP addresses that have been naughty. We’ll see who’s on the blacklist, just like Santa. | ||
5. **Generate a CSV file** with all the juicy details and ask if you want to open it. Because we care about your user experience. | ||
|
||
## How It Works | ||
|
||
1. **Requirements**: | ||
- Make sure you have `Python 3.x` installed. If you don’t, you’re going to have a bad time. | ||
- Install the required libraries by running: `pip install -r requirements.txt` | ||
- Spamhouse Query key | ||
This little gem is your one-stop-shop for parsing, analyzing, and reporting on DMARC reports, with the added bonus of | ||
fetching these reports directly from your email. | ||
Think of it like a Swiss Army knife, but for email security nerds. | ||
And like all good Swiss Army knives, it's sharp, versatile, and slightly dangerous if handled improperly. | ||
|
||
## Features | ||
|
||
- **Parse and Analyze DMARC Reports**: Because deciphering XML files manually is about as fun as a root canal. | ||
- **Download Attachments from Email**: Automatically fetch DMARC reports from your email account. Supports both basic authentication and OAuth2 for those fancy MFA setups. | ||
- **Detailed Reporting**: Calculates the number and ratio of emails that would be lost if DMARC had p=reject. Also tells you which IPs are blacklisted, because who doesn't love a good blacklist? | ||
- **CSV and Summary Output**: Save your analysis results to a CSV file and a summary text file. Perfect for impressing your boss or confusing your enemies. | ||
|
||
## Installation | ||
|
||
First, clone this repository to your local machine. You know the drill: | ||
|
||
```bash | ||
git clone https://github.com/yourusername/dmarc-report-analyzer.git | ||
cd dmarc-report-analyzer | ||
# Optional | ||
python3 -m venv env | ||
source env/bin/activate # On Windows use `env\Scripts\activate` | ||
# Mandatory | ||
pip install -r requirements.txt | ||
``` | ||
|
||
2. **Running the Script**: | ||
- Place your DMARC report files in a directory and call it `dmarc_check`. | ||
- Update the script at line 18 where you add the Spamhouse query key | ||
- Open your terminal or command prompt. | ||
- Navigate to the directory where the script is located. | ||
- Run the script by typing: `python dmarc_report_analyzer.py` | ||
- Sit back, relax, and enjoy a beverage of your choice. The script will take care of the rest. | ||
## Configuration | ||
Before you run the analyzer, you'll need to set up your configuration file. | ||
Because nothing says "I'm ready to analyze" like a well-configured `config.ini`. | ||
|
||
3. **Output**: | ||
- The script will create a CSV file named `dmarc_report_analysis.csv` in the current working directory. | ||
- It will log the progress and results, showing you the path to the final CSV file. | ||
- You’ll be prompted if you want to open the CSV file. Type `yes` if you do, or `no` if you want to keep the suspense. | ||
```bash | ||
cd config/ | ||
cp config.ini.example config.ini | ||
``` | ||
|
||
## Example Usage | ||
Open the config.ini with your favourite editor and fill all the fields :) | ||
|
||
### Tips | ||
#### Spamhaus | ||
- Visit this page https://www.spamhaus.com/free-trial/sign-up-for-a-free-data-query-service-account/ | ||
- Once you registered and confirmed your account go to https://portal.spamhaus.com/ | ||
- Go to Products -> DQS | ||
- Here you will find your **Query Key** | ||
#### Gmail and Password | ||
- Visit https://myaccount.google.com/ | ||
- Click on **Security** (on left menu) | ||
- Go to **How you sign in to Google** part and click on **2-Step Verification** | ||
- Scroll down to **App Password** and add one for this script | ||
- Copy and paste in the config the password | ||
|
||
## Usage | ||
To run the analyzer, simply execute the main.py script. It will ask if you want to download DMARC reports from an email account, and then proceed to analyze the reports in the specified directory. | ||
|
||
```bash | ||
python main.py | ||
``` | ||
|
||
Here’s a quick rundown of how to use the script: | ||
## Example | ||
Here's a quick rundown of what you'll see: | ||
|
||
```sh | ||
# Navigate to your script directory | ||
cd path/to/your/script | ||
- The script will ask if you want to download DMARC reports from an email account. | ||
- If you say "yes", it will fetch the reports and save them in the dmarc_check directory. | ||
- It will then analyze the reports and produce a summary of emails that failed SPF/DKIM checks, blacklisted IPs, and the potential impact if DMARC had p=reject. | ||
- Results are saved to dmarc_report_analysis.csv and summary.txt because we believe in both precision and verbosity. | ||
|
||
# Run the script | ||
python dmarc_report_analyzer.py | ||
``` | ||
## License | ||
This project is licensed under the MIT License. Because sharing is caring. | ||
|
||
## Contact | ||
If you run into any issues or have any questions, you’re probably not alone. | ||
## Disclaimer | ||
This tool is provided as-is, without any guarantees. Use at your own risk. Side effects may include enhanced email security knowledge and a sudden appreciation for XML parsing. | ||
|
||
Feel free to reach out ! | ||
Remember, folks, if you don't document it, it didn't happen. So keep those logs handy and those configs tight. Happy analyzing! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
[spamhaus] | ||
query_key = XXXX | ||
domain = zen.dq.spamhaus.net | ||
|
||
[email] | ||
imap_server = imap.gmail.com | ||
email_user = [email protected] | ||
|
||
; Please, use an app password for non-MFA | ||
email_pass = password | ||
|
||
; Set to true if using MFA and OAuth2 | ||
use_mfa = false | ||
|
||
credentials_json = vault/credentials.json | ||
token_json = vault/token.json | ||
scopes = https://mail.google.com/ | ||
redirect_uri = YOUR_OAUTH_REDIRECT_URI |
Oops, something went wrong.