gitea-admin/gh-christianlouis-dmarq
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive documentation for DMARQ, including user guides, deployment instructions, and feature descriptions

Browse Source 
- Created main documentation index and user guide with sections on getting started, dashboard overview, managing domains, and reports.
- Added detailed deployment guide for Docker and manual installation.
- Included user-friendly explanations of DMARC, its benefits, and how to manage domains and reports.
- Implemented visual assets for dashboard, domains, IMAP, and reports.
- Established requirements for documentation build using MkDocs and Material theme.
- Integrated navigation structure for easy access to all documentation sections.
This commit is contained in:
Christian Krakau-Louis
2025-04-21 01:49:34 +02:00
parent 1b79ec4f20
commit 5e8b1f033f
29 changed files with 1947 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user_guide/dashboard.md
+68
View File
@@ -0,0 +1,68 @@
# DMARQ Dashboard
The DMARQ dashboard provides an at-a-glance view of your email authentication status and recent issues.
## Overview
When you log in to DMARQ, you'll be presented with the main dashboard that displays key metrics about your DMARC compliance and email authentication status. The dashboard is designed to give you immediate insights into your email security posture.
## Dashboard Components
### DMARC Compliance Rate
This section shows the percentage of emails passing DMARC (both SPF and/or DKIM aligned) out of total emails. A higher compliance rate indicates that your email authentication is working correctly.
- **Compliance Gauge**: Visual representation of your current compliance rate
- **Trend Line**: Chart showing compliance rate over time
- **Failure Count**: Number of messages that failed DMARC checks
### Policy Enforcement Trends
This section visualizes how your domain's DMARC policy and enforcement have evolved:
- **Timeline Chart**: Shows the proportion of emails that were quarantined/rejected over time
- **Policy Change Markers**: Indicators of when policy changed from `none → quarantine → reject`
- **Blocked Email Statistics**: Bar chart showing how many spoofed emails were blocked per month
### DNS Record Health Check
This panel lists the essential DNS records for email authentication:
- **SPF**: Status of your SPF TXT record
- **DKIM**: List of DKIM selectors in use from aggregate reports
- **DMARC**: Your domain's DMARC record and key tags (p= policy, rua, ruf, pct, etc.)
- **MX**: Status of your mail exchanger records
- **BIMI**: Status of your Brand Indicators for Message Identification record
Each record is displayed with its actual value and a status indicator.
### Alerts Summary
This section highlights recent alerts or important notices:
- **Recent Alerts**: List of the last several alerts with severity indicators
- **Quick Actions**: Options to resolve or dismiss alerts
### Forensic Report Drilldown
For detailed investigation of DMARC failures:
- **Filtering**: Filter reports by date, source IP, or sending source
- **Detailed View**: Examine specifics of each forensic report
- **Header Analysis**: Option to view full email headers for advanced troubleshooting
## Customizing the Dashboard
You can customize various aspects of the dashboard:
1. **Date Range**: Adjust the time period for displayed data
2. **View Preferences**: Choose which metrics are most important to you
3. **Refresh Rate**: Set how often data is automatically refreshed
## Next Steps
After reviewing your dashboard, you may want to:
- [Manage your domains](domains.md) to add or configure additional domains
- [Review detailed reports](reports.md) for deeper analysis
- [Configure settings](settings.md) to adjust notification preferences
docs/user_guide/deployment_guide.md
+336
View File
@@ -0,0 +1,336 @@
# DMARQ Deployment Guide
This guide provides step-by-step instructions for deploying DMARQ in various environments.
## Table of Contents
1. [Docker Deployment (Recommended)](#docker-deployment-recommended)
2. [Manual Installation](#manual-installation)
3. [Environment Configuration](#environment-configuration)
4. [Database Setup](#database-setup)
5. [Production Best Practices](#production-best-practices)
6. [Upgrading](#upgrading)
## Docker Deployment (Recommended)
The easiest way to deploy DMARQ is using Docker and Docker Compose. This approach packages all dependencies and provides a consistent environment.
### Prerequisites
- Docker Engine 20.10.0 or later
- Docker Compose v2.0.0 or later
- 2GB RAM minimum (4GB recommended)
- 20GB storage space
### Deployment Steps
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/dmarq.git
cd dmarq
```
2. **Configure environment variables**
Create a `.env` file in the project root:
```
# Database Configuration
DB_TYPE=sqlite # or postgres for production
DB_PATH=./data/dmarq.db # for SQLite
# For PostgreSQL:
# DB_HOST=postgres
# DB_PORT=5432
# DB_USER=dmarq
# DB_PASS=secure_password
# DB_NAME=dmarq
# IMAP Configuration (optional)
IMAP_ENABLED=false
# IMAP_SERVER=mail.example.com
# IMAP_PORT=993
# IMAP_USERNAME=dmarc@example.com
# IMAP_PASSWORD=your_secure_password
# IMAP_USE_SSL=true
# IMAP_POLLING_INTERVAL=60
# Security Settings
SECRET_KEY=generate_a_secure_random_key
ALLOWED_HOSTS=localhost,127.0.0.1
```
Generate a secure random key for `SECRET_KEY`:
```bash
openssl rand -hex 32
```
3. **Start the containers**
```bash
docker-compose up -d
```
4. **Access the application**
Open your browser and navigate to `http://localhost:8000`
5. **Check container status**
```bash
docker-compose ps
```
### Updating the Deployment
To update to a newer version:
```bash
git pull
docker-compose down
docker-compose build
docker-compose up -d
```
## Manual Installation
For environments where Docker isn't available, you can install DMARQ manually.
### Prerequisites
- Python 3.9 or higher
- pip and virtualenv
- Node.js 16+ (if modifying frontend assets)
### Installation Steps
1. **Set up virtual environment**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
2. **Install dependencies**
```bash
cd backend
pip install -r requirements.txt
```
3. **Configure environment variables**
Create a `.env` file in the backend directory with the same variables as in the Docker deployment.
4. **Initialize the database**
```bash
cd app
python -m alembic upgrade head
```
5. **Start the application**
```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```
6. **Set up a production server**
For production, use a proper ASGI server like Uvicorn behind Nginx:
```bash
# Example systemd service
[Unit]
Description=DMARQ Application
After=network.target
[Service]
User=dmarq
WorkingDirectory=/path/to/dmarq/backend/app
ExecStart=/path/to/dmarq/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
Restart=always
[Install]
WantedBy=multi-user.target
```
## Environment Configuration
DMARQ can be configured through environment variables:
### Core Settings
| Variable | Description | Default |
|----------|-------------|---------|
| `DEBUG` | Enable debug mode | `false` |
| `SECRET_KEY` | Secret key for session security | Required |
| `ALLOWED_HOSTS` | Comma-separated list of allowed hosts | `localhost,127.0.0.1` |
### Database Settings
| Variable | Description | Default |
|----------|-------------|---------|
| `DB_TYPE` | Database type (sqlite, postgres) | `sqlite` |
| `DB_PATH` | Path to SQLite database file | `./data/dmarq.db` |
| `DB_HOST` | PostgreSQL host | - |
| `DB_PORT` | PostgreSQL port | `5432` |
| `DB_USER` | PostgreSQL username | - |
| `DB_PASS` | PostgreSQL password | - |
| `DB_NAME` | PostgreSQL database name | - |
### IMAP Settings
| Variable | Description | Default |
|----------|-------------|---------|
| `IMAP_ENABLED` | Enable IMAP report fetching | `false` |
| `IMAP_SERVER` | IMAP server address | - |
| `IMAP_PORT` | IMAP server port | `993` |
| `IMAP_USERNAME` | IMAP username | - |
| `IMAP_PASSWORD` | IMAP password | - |
| `IMAP_USE_SSL` | Use SSL for IMAP connection | `true` |
| `IMAP_POLLING_INTERVAL` | Minutes between polling | `60` |
## Database Setup
DMARQ supports SQLite (default) and PostgreSQL databases.
### SQLite (Default)
SQLite is suitable for smaller deployments with fewer domains and reports. No additional configuration is required as it works out of the box.
### PostgreSQL (Recommended for Production)
1. **Create a PostgreSQL database and user**
```sql
CREATE USER dmarq WITH PASSWORD 'secure_password';
CREATE DATABASE dmarq OWNER dmarq;
```
2. **Update environment variables**
```
DB_TYPE=postgres
DB_HOST=your_postgres_host
DB_PORT=5432
DB_USER=dmarq
DB_PASS=secure_password
DB_NAME=dmarq
```
3. **Run database migrations**
```bash
cd backend/app
python -m alembic upgrade head
```
## Production Best Practices
For production deployments, consider the following:
1. **Use HTTPS**
Set up SSL/TLS with a valid certificate using a reverse proxy like Nginx:
```nginx
server {
listen 80;
server_name dmarq.example.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl;
server_name dmarq.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
2. **Regular Backups**
Set up regular database backups:
```bash
# For PostgreSQL
pg_dump -U dmarq dmarq > dmarq_backup_$(date +%Y%m%d).sql
# For SQLite
sqlite3 data/dmarq.db .dump > dmarq_backup_$(date +%Y%m%d).sql
```
3. **Monitoring**
Monitor the application using tools like Prometheus and Grafana.
4. **Secure Credentials**
Store sensitive credentials in a secure vault rather than environment variables for production environments.
## Upgrading
### Major Version Upgrades
1. **Backup your data**
```bash
# For PostgreSQL
pg_dump -U dmarq dmarq > dmarq_backup_before_upgrade.sql
# For SQLite
sqlite3 data/dmarq.db .dump > dmarq_backup_before_upgrade.sql
```
2. **Update the repository**
```bash
git fetch --tags
git checkout v2.0.0 # Replace with your target version
```
3. **Update dependencies**
```bash
pip install -r requirements.txt
```
4. **Run database migrations**
```bash
cd backend/app
python -m alembic upgrade head
```
5. **Restart the application**
```bash
# For Docker
docker-compose down
docker-compose up -d
# For manual installations
sudo systemctl restart dmarq
```
### Minor Version Upgrades
For minor version upgrades (e.g., 1.1.0 to 1.2.0), the process is similar but generally has less risk of breaking changes:
```bash
git fetch --tags
git checkout v1.2.0 # Replace with your target version
docker-compose down
docker-compose up -d
```
Always check the release notes for any specific upgrade instructions or breaking changes.
docs/user_guide/domains.md
+89
View File
@@ -0,0 +1,89 @@
# Managing Domains
This guide explains how to add, configure, and manage domains in DMARQ.
## Adding a New Domain
To add a new domain for DMARC monitoring in DMARQ:
1. Navigate to **Domains** in the main navigation
2. Click the **Add Domain** button
3. Enter your domain name (e.g., `example.com`)
4. Click **Verify** to ensure the domain is valid
5. Click **Add Domain** to confirm
DMARQ will add the domain to your account and begin monitoring for DMARC reports related to this domain.
## Domain Settings
For each domain, you can configure several settings:
### DMARC Policy Configuration
DMARQ allows you to view and optionally manage your DMARC policy:
- **Current Policy**: View your active DMARC policy (none, quarantine, reject)
- **Policy History**: Track changes to your DMARC policy over time
- **Policy Recommendations**: Get suggestions for improving your DMARC implementation based on your compliance rate
### DNS Record Management
If you've enabled Cloudflare integration, you can manage your email authentication DNS records directly from DMARQ:
- **View Current Records**: See all SPF, DKIM, DMARC, and BIMI records
- **Update Records**: Modify existing records as your email infrastructure changes
- **Add New Records**: Create new records like additional DKIM selectors
To update a record:
1. Find the record you want to change in the DNS Records section
2. Click **Edit**
3. Make your changes in the record editor
4. Click **Save** to apply the changes to your DNS
### Report Delivery Settings
Configure where and how DMARC reports are delivered:
- **RUA Email**: The email address receiving aggregate reports
- **RUF Email**: The email address receiving forensic reports
- **Report Frequency**: How often you want to receive reports
## Domain Health Check
DMARQ provides a health check feature for each domain:
1. Navigate to the domain details page
2. Click **Run Health Check** to analyze your domain's email authentication setup
3. Review the results, which include:
- SPF record validation
- DKIM selector verification
- DMARC record syntax check
- MX record confirmation
- BIMI record validation (if applicable)
## Domain Groups
If you manage multiple domains, you can organize them into groups:
1. Go to the **Domains** page
2. Click **Manage Groups**
3. Create a new group and give it a name
4. Drag and drop domains into the group
Groups allow you to:
- View aggregate statistics across multiple related domains
- Apply settings changes to multiple domains at once
- Organize domains by business unit, client, or purpose
## Removing a Domain
To remove a domain from DMARQ:
1. Navigate to the **Domains** page
2. Find the domain you wish to remove
3. Click the **Options** menu (three dots)
4. Select **Remove Domain**
5. Confirm the removal
Note that removing a domain will delete all stored DMARC reports for that domain.
docs/user_guide/getting_started.md
+174
View File
@@ -0,0 +1,174 @@
# DMARQ User Guide
![DMARQ Logo](../../backend/app/static/img/logotype_horizontal_dark.png)
*Secure Email. Simplified.*
## Table of Contents
1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Dashboard Overview](#dashboard-overview)
4. [Managing Domains](#managing-domains)
5. [Viewing Reports](#viewing-reports)
6. [IMAP Configuration](#imap-configuration)
7. [Settings](#settings)
8. [Troubleshooting](#troubleshooting)
9. [FAQ](#faq)
## Introduction
DMARQ is a modern, user-friendly tool designed to make DMARC (Domain-based Message Authentication, Reporting, and Conformance) implementation accessible for everyone. This guide will help you navigate the features and functionalities of DMARQ to effectively manage your email security.
### What is DMARC?
DMARC (Domain-based Message Authentication, Reporting, and Conformance) is an email authentication protocol that builds upon SPF and DKIM. It helps prevent email spoofing, phishing, and other email-based attacks by allowing domain owners to specify how email messages that fail authentication should be handled.
### Benefits of Using DMARQ
- **Simplified Monitoring**: Easily track DMARC compliance across your domains
- **Actionable Insights**: Get clear visualization of authentication failures and patterns
- **Automated Processing**: Automatically retrieve and parse DMARC reports
- **Policy Management**: Manage and adjust your DMARC policies as your compliance improves
## Getting Started
### System Requirements
- Modern web browser (Chrome, Firefox, Safari, Edge)
- Internet connection
- DMARC reports for your domain(s)
### First-Time Setup
1. **Access the DMARQ dashboard**: Navigate to the URL provided by your administrator
2. **Create an account**: Click "Sign Up" and follow the registration process
3. **Add your first domain**: Click "Add Domain" on the dashboard and enter your domain details
4. **Upload a DMARC report**: Use the "Upload Report" button to add your first report
## Dashboard Overview
The DMARQ dashboard provides an at-a-glance view of your email authentication status:
![Dashboard Screenshot](placeholder_dashboard.png)
### Key Elements
- **Domain Summary**: Shows all monitored domains with compliance rates
- **Email Volume**: Displays the total number of emails processed
- **Compliance Rate**: Shows the overall DMARC pass rate
- **Recent Reports**: Lists the most recent DMARC reports received
## Managing Domains
### Adding a Domain
1. Click "Domains" in the main navigation
2. Click the "Add Domain" button
3. Enter the domain name and description
4. Click "Save"
### Domain Details
Click on any domain name to view detailed information including:
- Compliance rate over time
- Email volume trends
- Source IP breakdown
- DMARC, SPF, and DKIM records
### DNS Records
DMARQ provides guidance on setting up proper DNS records for email authentication:
1. Navigate to the domain details page
2. Click "Check DNS" to see current records
3. Follow the recommendations to improve your configuration
## Viewing Reports
### Report List
The Reports page shows all DMARC reports received for your domains:
1. Click "Reports" in the main navigation
2. Use filters to narrow down by date, domain, or compliance status
3. Click on a report to view details
### Report Details
The report detail view includes:
- Sending organization information
- Authentication results (SPF, DKIM, DMARC)
- Source IP breakdown
- Recommended actions for failed authentications
## IMAP Configuration
DMARQ can automatically fetch DMARC reports from your email account:
### Setting Up IMAP
1. Go to "Settings" > "IMAP Configuration"
2. Enter your IMAP server details:
- Server address
- Port
- Username
- Password
- SSL/TLS settings
3. Set polling interval (how often to check for new reports)
4. Click "Test Connection" to verify
5. Save your settings
### Managing Report Fetching
- Click "Fetch Now" to retrieve reports immediately
- View the status of the background process
- Check logs for any issues with fetching reports
## Settings
### User Settings
Manage your account information and preferences:
- Update your profile information
- Change password
- Set notification preferences
### Domain Settings
Adjust settings for your domains:
- Set default DMARC policy
- Configure alerts for compliance issues
- Set up automatic report archiving
## Troubleshooting
### Common Issues
- **No reports showing**: Check your IMAP settings or try uploading reports manually
- **Authentication failures**: Review DNS records for proper SPF and DKIM configuration
- **Slow dashboard**: Try filtering for a shorter date range
### Support Resources
- Documentation: [DMARQ Docs](https://example.com/docs)
- Community Forum: [DMARQ Community](https://example.com/community)
- Support Email: support@example.com
## FAQ
### What is a good compliance rate?
A compliance rate of 98% or higher is considered excellent. Rates between 90-98% indicate room for improvement, while rates below 90% suggest significant issues that need attention.
### How often should I check my DMARC reports?
For active monitoring, weekly checks are recommended. When implementing changes to SPF or DKIM, more frequent monitoring can help ensure those changes are working properly.
### Can I use DMARQ for multiple domains?
Yes! DMARQ is designed to handle multiple domains. You can add each domain to monitor and see aggregate statistics across all your domains.
docs/user_guide/reports.md
+110
View File
@@ -0,0 +1,110 @@
# DMARC Reports
This guide explains how to work with DMARC reports in DMARQ.
## Types of DMARC Reports
DMARQ supports two types of DMARC reports:
### Aggregate Reports (RUA)
Aggregate reports provide statistical data about email authentication results. These reports:
- Are typically sent daily by email providers
- Contain summaries of email volumes and authentication results
- Do not include the content of individual emails
- Are XML files, often compressed
### Forensic Reports (RUF)
Forensic reports provide information about individual messages that failed DMARC authentication:
- Include details about specific authentication failures
- May contain email headers and sometimes partial content
- Help diagnose specific delivery issues
- Not all providers send forensic reports due to privacy concerns
## Viewing Reports
### Aggregate Reports List
To view your aggregate reports:
1. Navigate to **Reports** in the main navigation
2. Select the **Aggregate** tab
3. Use filters to narrow down reports by:
- Date range
- Source organization (e.g., Google, Yahoo, Microsoft)
- Domain (if monitoring multiple domains)
- Policy applied (none, quarantine, reject)
The report list shows:
- Report date
- Sending organization
- Number of messages
- Pass/fail statistics
- DMARC policy applied
### Aggregate Report Details
To view details of a specific aggregate report:
1. Click on any report in the list
2. Review the detailed information, including:
- Source IP addresses
- Message counts
- SPF and DKIM alignment results
- Sending sources (by domain and IP)
- Pass/fail rates by source
### Forensic Reports
To view forensic reports (when available):
1. Navigate to **Reports** in the main navigation
2. Select the **Forensic** tab
3. Use filters similar to aggregate reports
4. Click on any report to view details about the specific authentication failure
## Understanding Report Data
### Key Metrics
Important metrics to look for in DMARC reports:
- **SPF Alignment**: Whether the domain in the From header matches the domain that passed SPF
- **DKIM Alignment**: Whether the domain in the From header matches the domain in the DKIM signature
- **Source IPs**: The IP addresses sending email on behalf of your domain
- **Volume Trends**: Changes in email volume over time
- **Failure Patterns**: Recurring patterns in authentication failures
### Report Visualization
DMARQ provides several visualizations to help understand report data:
- **Source Distribution**: Chart showing email volume by sending source
- **Authentication Results**: Breakdown of SPF, DKIM, and alignment results
- **Geographic Distribution**: Map showing the origin of emails by country
- **Timeline View**: Changes in email authentication over time
## Importing Reports Manually
If you need to import DMARC reports manually:
1. Navigate to **Reports** in the main navigation
2. Click **Upload Report**
3. Select the report file from your computer (XML, ZIP, or GZ format)
4. Click **Upload** to process the report
DMARQ will parse the report and add it to your database.
## Exporting Report Data
To export report data for external analysis:
1. Navigate to the report list or detail view
2. Click **Export**
3. Choose your preferred format:
- CSV for spreadsheet analysis
- JSON for programmatic processing
- PDF for sharing with stakeholders
4. Select the data points to include
5. Click **Generate Export** to download the file