Initial commit

config/config.example.yml

@@ -0,0 +1,103 @@
+app:
+  name: "DMARC Sentinel"
+  base_url: "https://sentinel.tukutoi.com"
+  timezone: "Europe/Zurich"
+  poll_interval_minutes: 30
+  database_url: "sqlite:////app/data/dmarc-sentinel.sqlite3"
+  log_level: "INFO"
+  max_attachment_decompressed_mb: 20
+  max_attachment_compressed_mb: 10
+  max_attachments_per_message: 20
+  max_reports_per_message: 20
+  max_reports_per_archive: 20
+  max_archive_compression_ratio: 100
+  max_xml_records_per_report: 10000
+  max_record_count: 10000000
+  max_report_future_days: 3
+  max_report_past_days: 3650
+  max_reports_per_poll: 200
+
+security:
+  dashboard_auth_enabled: true
+  dashboard_username_env: "DASHBOARD_USERNAME"
+  dashboard_password_env: "DASHBOARD_PASSWORD"
+  api_token_required: true
+  homepage_token_env: "HOMEPAGE_API_TOKEN"
+
+llm:
+  provider: "openai"
+  api_key_env: "OPENAI_API_KEY"
+  model: "gpt-4.1-mini"
+  temperature: 0.2
+  timeout_seconds: 45
+  max_retries: 2
+  generate_alert_explanations: true
+  generate_daily_summary: true
+  generate_weekly_summary: true
+  store_llm_outputs: true
+  send_raw_xml_to_llm: false
+  send_raw_email_to_llm: false
+  system_prompt_path: "config/prompts/system.md"
+  alert_prompt_path: "config/prompts/alert_explanation.md"
+  digest_prompt_path: "config/prompts/posture_digest.md"
+  weekly_prompt_path: "config/prompts/weekly_summary.md"
+
+inboxes:
+  - id: "tukutoi"
+    label: "Tukutoi"
+    domain: "tukutoi.com"
+    imap_host: "mail.tukutoi.com"
+    imap_port: 993
+    imap_ssl: true
+    username_env: "TUKUTOI_IMAP_USER"
+    password_env: "TUKUTOI_IMAP_PASSWORD"
+    folder: "DMARC"
+    recipient: "dmarcreports@tukutoi.com"
+    processed_folder: "DMARC/Processed"
+    failed_folder: "DMARC/Failed"
+    move_after_success: false
+    move_after_failure: false
+    mark_seen_after_success: true
+    enabled: true
+
+known_senders:
+  tukutoi.com:
+    - id: "mailcow"
+      name: "mailcow outbound"
+      ip_allowlist:
+        - "REPLACE_WITH_MAILCOW_OUTBOUND_IP/32"
+      dkim_domains:
+        - "tukutoi.com"
+      spf_domains:
+        - "tukutoi.com"
+    - id: "google_workspace"
+      name: "Google Workspace"
+      ip_allowlist: []
+      dkim_domains:
+        - "tukutoi.com"
+      spf_domains:
+        - "_spf.google.com"
+    - id: "mailchimp"
+      name: "Mailchimp"
+      ip_allowlist: []
+      dkim_domains: []
+      spf_domains: []
+
+alerts:
+  email:
+    enabled: true
+    smtp_host_env: "ALERT_SMTP_HOST"
+    smtp_port_env: "ALERT_SMTP_PORT"
+    smtp_user_env: "ALERT_SMTP_USER"
+    smtp_password_env: "ALERT_SMTP_PASSWORD"
+    from_env: "ALERT_EMAIL_FROM"
+    to_env: "ALERT_EMAIL_TO"
+  thresholds:
+    unknown_source_fail_count: 10
+    unknown_source_fail_rate_percent: 5
+    known_source_fail_rate_percent: 2
+    total_volume_spike_multiplier: 3
+    total_volume_drop_percent: 80
+    min_messages_for_rate_alert: 20
+    repeated_failure_days: 2
+    missing_reporter_days: 3

config/prompts/alert_explanation.md

@@ -0,0 +1,13 @@
+Explain this DMARC alert to a business owner/admin.
+
+Be precise, do not invent facts, distinguish likely spoofing from confirmed compromise, and provide concrete next steps.
+
+DMARC aggregate source IPs are observed transmitting IPs from the reporter's point of view. They may be final-hop relays, forwarders, mailing lists, or security gateways, not necessarily the original sender configured by the domain owner.
+
+If SPF fails but DKIM aligns and DMARC passes, do not frame the IP as a threat or as something to add to SPF. Explain that forwarding or an intermediary relay commonly breaks SPF while preserving DKIM, and that DMARC passed because DKIM proved authorization.
+
+If a source appears to be a direct legitimate sender, say to authorize it correctly by fixing SPF/DKIM alignment and then classifying it as approved.
+
+If a source is not legitimate, say not to add it to known senders, not to loosen SPF/DKIM for it, and to rely on DMARC enforcement after legitimate senders are aligned. Mention that quarantine/reject helps receivers handle unauthorized spoofing attempts, while DNS fixes are only for legitimate senders.
+
+Return exactly one JSON object with these keys: summary, risk, recommended_action, confidence.

config/prompts/posture_digest.md

@@ -0,0 +1,17 @@
+Write a current DMARC posture report for the admin using all supplied deterministic telemetry and all open alerts.
+
+Base the report on unresolved/open risk across all imported data, not only one report day.
+
+Mention exact counts/rates, important failing or unknown sources, relevant reporters, and concrete remediation.
+
+DMARC aggregate source IPs are observed transmitting IPs from the reporter's point of view. They may be final-hop relays, forwarders, mailing lists, or security gateways, not necessarily the original sender configured by the domain owner.
+
+For SPF-fail, DKIM-pass, DMARC-pass observations, explain that this commonly indicates forwarding or an intermediary relay. Do not recommend adding those observed relay IPs to SPF solely because they appear in aggregate reports.
+
+For unknown failing sources, explain both branches:
+- If legitimate: authorize/fix SPF/DKIM/alignment and classify the sender.
+- If not legitimate: do not authorize it, do not add it to known senders, leave it unknown, and use DMARC enforcement such as quarantine/reject once legitimate senders are aligned.
+
+Make clear that DMARC quarantine/reject helps receivers handle unauthorized spoofing attempts; it does not fix legitimate sender misconfiguration.
+
+Do not claim mailbox compromise from DMARC aggregate data alone. Return only JSON matching required_json_schema.

config/prompts/system.md

@@ -0,0 +1,5 @@
+You are an expert email authentication and DMARC operations analyst.
+
+Explain deterministic DMARC telemetry to a business owner/admin. Do not invent facts. Distinguish confirmed facts from likely interpretations. Never claim an account is compromised solely from DMARC aggregate data.
+
+Provide practical next steps. Output only valid JSON matching the requested schema.

config/prompts/weekly_summary.md

@@ -0,0 +1,5 @@
+Write a weekly DMARC posture summary for the admin.
+
+Include high-level posture, trend changes, new senders, persistent failures, whether DMARC policy posture looks safe, and recommended operational actions.
+
+Only say to consider stricter policy if the metrics support it and legitimate senders appear aligned.