feat: add email security posture checks

Author: sanmaxdev

README.md

@@ -13,6 +13,7 @@ It turns quick domain checks into clean JSON reports today, then client-ready HT
 - HTTPS reachability
 - HTTP security headers
 - TLS certificate expiry
+- MX, SPF, and DMARC email-security posture
 - Risk scoring with actionable findings
 - JSON report export
 
@@ -57,7 +58,7 @@ SentinelDeck is **passive-first**. The MVP avoids intrusive vulnerability scanni
 - [x] JSON report export
 - [x] HTTP header checks
 - [x] TLS expiry check
-- [ ] SPF/DMARC/MX checks
+- [x] SPF/DMARC/MX checks
 - [ ] HTML report
 - [ ] PDF export
 - [ ] Screenshot evidence

src/sentineldeck/risk/scoring.py

@@ -79,4 +79,55 @@ def build_findings(checks: dict) -> list[Finding]:
             evidence={"days_remaining": tls.get("days_remaining"), "expires_at": tls.get("expires_at")},
         ))
 
+    email = checks.get("email_security", {})
+    if email:
+        mx = email.get("mx", {})
+        spf = email.get("spf", {})
+        dmarc = email.get("dmarc", {})
+        if not mx.get("present"):
+            findings.append(Finding(
+                id="mx-missing",
+                title="No MX records found",
+                severity="medium",
+                description="The domain does not publish MX records for receiving email.",
+                recommendation="Publish correct MX records if the domain sends or receives business email.",
+                evidence=mx,
+            ))
+        if not spf.get("present"):
+            findings.append(Finding(
+                id="spf-missing",
+                title="SPF record is missing",
+                severity="medium",
+                description="The domain does not publish an SPF record to restrict allowed mail senders.",
+                recommendation="Add an SPF TXT record that lists approved sending services and ends with -all or ~all.",
+                evidence=spf,
+            ))
+        elif spf.get("policy") in {None, "+all", "?all", "~all"}:
+            findings.append(Finding(
+                id="spf-weak-policy",
+                title="SPF policy is weak",
+                severity="low",
+                description="The SPF record does not use a strict fail policy.",
+                recommendation="Review sending sources and move toward a stricter -all policy when safe.",
+                evidence=spf,
+            ))
+        if not dmarc.get("present"):
+            findings.append(Finding(
+                id="dmarc-missing",
+                title="DMARC record is missing",
+                severity="medium",
+                description="The domain does not publish DMARC, making spoofed-email handling unclear.",
+                recommendation="Add a DMARC TXT record at _dmarc with at least p=none for monitoring, then move to quarantine or reject.",
+                evidence=dmarc,
+            ))
+        elif dmarc.get("policy") in {None, "none"}:
+            findings.append(Finding(
+                id="dmarc-monitor-only",
+                title="DMARC is monitor-only",
+                severity="low",
+                description="The domain publishes DMARC but does not request enforcement.",
+                recommendation="After monitoring legitimate mail flow, move DMARC policy to quarantine or reject.",
+                evidence=dmarc,
+            ))
+
     return findings

src/sentineldeck/scanner.py

@@ -3,6 +3,7 @@
 from sentineldeck.models import ScanReport
 from sentineldeck.risk.scoring import build_findings, grade, score_findings
 from sentineldeck.scanners.domain import normalize_domain, resolve_domain
+from sentineldeck.scanners.email_security import analyze_email_security
 from sentineldeck.scanners.http_headers import fetch_headers, missing_security_headers
 from sentineldeck.scanners.tls import inspect_tls
 
@@ -14,12 +15,14 @@ def scan_domain(target: str) -> ScanReport:
     dns = resolve_domain(domain)
     http = fetch_headers(domain)
     tls = inspect_tls(domain)
+    email_security = analyze_email_security(domain)
 
     report.checks = {
         "dns": dns,
         "http": http,
         "missing_security_headers": missing_security_headers(http.get("headers", {})),
         "tls": tls,
+        "email_security": email_security,
     }
     report.findings = build_findings(report.checks)
     report.risk_score = score_findings(report.findings)

src/sentineldeck/scanners/email_security.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from typing import Callable
+
+DnsQuery = Callable[[str, str], str]
+
+
+def query_dns(name: str, record_type: str) -> str:
+    """Query DNS using common system tools without adding runtime dependencies."""
+    commands = [
+        ["dig", "+short", record_type, name],
+        ["host", "-t", record_type, name],
+    ]
+    for command in commands:
+        try:
+            completed = subprocess.run(command, check=False, capture_output=True, text=True, timeout=10)
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+        if completed.returncode == 0 and completed.stdout.strip():
+            return completed.stdout
+    return ""
+
+
+def parse_txt_records(output: str) -> list[str]:
+    records: list[str] = []
+    for line in output.splitlines():
+        parts = re.findall(r'"([^"]*)"', line)
+        if parts:
+            records.append("".join(parts).strip())
+        elif line.strip():
+            records.append(line.strip())
+    return records
+
+
+def parse_mx_records(output: str) -> list[str]:
+    records: list[str] = []
+    for line in output.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if " mail is handled by " in line:
+            records.append(line.split(" mail is handled by ", 1)[1])
+        else:
+            records.append(line)
+    return records
+
+
+def extract_spf_policy(record: str | None) -> str | None:
+    if not record:
+        return None
+    mechanisms = record.lower().split()
+    for mechanism in ("-all", "~all", "?all", "+all"):
+        if mechanism in mechanisms:
+            return mechanism
+    return None
+
+
+def extract_dmarc_policy(record: str | None) -> str | None:
+    if not record:
+        return None
+    for part in record.split(";"):
+        key, _, value = part.strip().partition("=")
+        if key.lower() == "p":
+            return value.strip().lower() or None
+    return None
+
+
+def analyze_email_security(domain: str, query: DnsQuery = query_dns) -> dict:
+    mx_records = parse_mx_records(query(domain, "MX"))
+    txt_records = parse_txt_records(query(domain, "TXT"))
+    dmarc_records = parse_txt_records(query(f"_dmarc.{domain}", "TXT"))
+
+    spf_records = [record for record in txt_records if record.lower().startswith("v=spf1")]
+    dmarc_policy_records = [record for record in dmarc_records if record.lower().startswith("v=dmarc1")]
+    spf_record = spf_records[0] if spf_records else None
+    dmarc_record = dmarc_policy_records[0] if dmarc_policy_records else None
+
+    return {
+        "mx": {"present": bool(mx_records), "records": mx_records},
+        "spf": {
+            "present": bool(spf_records),
+            "records": spf_records,
+            "policy": extract_spf_policy(spf_record),
+        },
+        "dmarc": {
+            "present": bool(dmarc_policy_records),
+            "records": dmarc_policy_records,
+            "policy": extract_dmarc_policy(dmarc_record),
+        },
+    }

tests/test_email_security.py

@@ -0,0 +1,54 @@
+from sentineldeck.risk.scoring import build_findings
+from sentineldeck.scanners.email_security import analyze_email_security, parse_txt_records
+
+
+def test_parse_txt_records_joins_split_segments():
+    output = '"v=spf1 include:_spf.example.com " "-all"\n"other=value"\n'
+
+    assert parse_txt_records(output) == ["v=spf1 include:_spf.example.com -all", "other=value"]
+
+
+def test_parse_mx_records_preserves_null_mx():
+    from sentineldeck.scanners.email_security import parse_mx_records
+
+    assert parse_mx_records("0 .\n") == ["0 ."]
+
+
+def test_analyze_email_security_detects_present_controls():
+    dns_query = {
+        ("example.com", "MX"): "10 mail.example.com.\n",
+        ("example.com", "TXT"): '"v=spf1 mx -all"\n',
+        ("_dmarc.example.com", "TXT"): '"v=DMARC1; p=reject; rua=mailto:dmarc@example.com"\n',
+    }
+
+    result = analyze_email_security("example.com", query=lambda name, record_type: dns_query[(name, record_type)])
+
+    assert result["mx"]["present"] is True
+    assert result["spf"]["present"] is True
+    assert result["spf"]["policy"] == "-all"
+    assert result["dmarc"]["present"] is True
+    assert result["dmarc"]["policy"] == "reject"
+
+
+def test_analyze_email_security_handles_missing_records():
+    result = analyze_email_security("example.com", query=lambda name, record_type: "")
+
+    assert result["mx"]["present"] is False
+    assert result["spf"]["present"] is False
+    assert result["dmarc"]["present"] is False
+
+
+def test_build_findings_flags_missing_dmarc_and_weak_spf():
+    checks = {
+        "email_security": {
+            "mx": {"present": True, "records": ["10 mail.example.com."]},
+            "spf": {"present": True, "records": ["v=spf1 include:mail.example.com ~all"], "policy": "~all"},
+            "dmarc": {"present": False, "records": [], "policy": None},
+        }
+    }
+
+    findings = build_findings(checks)
+    finding_ids = {finding.id for finding in findings}
+
+    assert "dmarc-missing" in finding_ids
+    assert "spf-weak-policy" in finding_ids

tests/test_scanner.py

@@ -0,0 +1,19 @@
+from sentineldeck.scanner import scan_domain
+
+
+def test_scan_domain_includes_email_security(monkeypatch):
+    monkeypatch.setattr("sentineldeck.scanner.resolve_domain", lambda domain: {"resolved": True, "addresses": ["127.0.0.1"]})
+    monkeypatch.setattr("sentineldeck.scanner.fetch_headers", lambda domain: {"reachable": True, "headers": {}})
+    monkeypatch.setattr("sentineldeck.scanner.inspect_tls", lambda domain: {"valid": True, "days_remaining": 90})
+    monkeypatch.setattr(
+        "sentineldeck.scanner.analyze_email_security",
+        lambda domain: {
+            "mx": {"present": True, "records": ["10 mail.example.com."]},
+            "spf": {"present": True, "records": ["v=spf1 mx -all"], "policy": "-all"},
+            "dmarc": {"present": True, "records": ["v=DMARC1; p=reject"], "policy": "reject"},
+        },
+    )
+
+    report = scan_domain("example.com")
+
+    assert report.checks["email_security"]["dmarc"]["policy"] == "reject"