emlpeek 1.0.0__tar.gz

emlpeek-1.0.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: emlpeek
+Version: 1.0.0
+Summary: Email investigation tool
+Author-email: Your Name <you@example.com>
+License: MIT
+Keywords: email,investigation,forensics
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# emlpeek
+Email investigation tool

emlpeek-1.0.0/README.md

@@ -0,0 +1,2 @@
+# emlpeek
+Email investigation tool

emlpeek-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "emlpeek"
+version = "1.0.0"
+description = "Email investigation tool"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Your Name", email = "you@example.com" }]
+keywords = ["email", "investigation", "forensics"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["soc_email_investigator*"]

emlpeek-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

emlpeek-1.0.0/src/emlpeek.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: emlpeek
+Version: 1.0.0
+Summary: Email investigation tool
+Author-email: Your Name <you@example.com>
+License: MIT
+Keywords: email,investigation,forensics
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# emlpeek
+Email investigation tool

emlpeek-1.0.0/src/emlpeek.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/emlpeek.egg-info/PKG-INFO
+src/emlpeek.egg-info/SOURCES.txt
+src/emlpeek.egg-info/dependency_links.txt
+src/emlpeek.egg-info/top_level.txt
+src/soc_email_investigator/__init__.py
+src/soc_email_investigator/extract.py
+src/soc_email_investigator/main.py
+src/soc_email_investigator/report.py
+src/soc_email_investigator/rules.py

emlpeek-1.0.0/src/emlpeek.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

emlpeek-1.0.0/src/emlpeek.egg-info/top_level.txt

@@ -0,0 +1 @@
+soc_email_investigator

emlpeek-1.0.0/src/soc_email_investigator/extract.py

@@ -0,0 +1,125 @@
+from pathlib import Path
+from email import policy
+from email.parser import BytesParser
+from urllib.parse import urlparse
+import re
+
+URL_RE = re.compile(r"https?://[^\s\"'<>()]+", re.IGNORECASE)
+EMAIL_LINE_RE = re.compile(r"^\s*([A-Z0-9._%+\-]+@[^>\s]+)\s*$", re.IGNORECASE)
+
+def _extract_address_domain(address: str | None) -> str | None:
+    if not address:
+        return None
+    # Strip common forms like: "Name <user@domain.com>"
+    if "<" in address and ">" in address:
+        addr = address.split("<", 1)[1].split(">", 1)[0].strip()
+    else:
+        addr = address.strip()
+    if "@" not in addr:
+        return None
+    return addr.split("@", 1)[1].lower()
+
+def _extract_urls(text: str) -> list[str]:
+    if not text:
+        return []
+    # Try common URL pattern
+    urls = URL_RE.findall(text)
+    # Cleanup trailing punctuation
+    cleaned = []
+    for u in urls:
+        cleaned.append(u.rstrip(").,;:!?\"'"))
+    return cleaned
+
+def _url_host(url: str) -> str | None:
+    try:
+        parsed = urlparse(url)
+        host = parsed.hostname
+        if host:
+            return host
+    except Exception:
+        pass
+    return None
+
+def extract_from_eml(eml_path: Path) -> dict:
+    raw = eml_path.read_bytes()
+
+    msg = BytesParser(policy=policy.default).parsebytes(raw)
+
+    headers_text = ""
+    received_lines = []
+    for k, v in msg.raw_items():
+        # raw_items returns header fields as provided; we store full header text for "Received:"
+        if k is not None and k.lower() == "received":
+            received_lines.append(str(v).strip())
+        # For completeness, keep a header text dump too
+        headers_text += f"{k}: {v}\n" if k else f"{v}\n"
+
+    # Body extraction (best-effort)
+    body_parts = []
+    if msg.is_multipart():
+        for part in msg.walk():
+            ctype = part.get_content_type()
+            disp = str(part.get("Content-Disposition") or "")
+            if ctype in ("text/plain", "text/html") and "attachment" not in disp.lower():
+                try:
+                    body_parts.append(part.get_content())
+                except Exception:
+                    # fallback decode
+                    payload = part.get_payload(decode=True) or b""
+                    charset = part.get_content_charset() or "utf-8"
+                    body_parts.append(payload.decode(charset, errors="replace"))
+    else:
+        try:
+            body_parts.append(msg.get_content())
+        except Exception:
+            payload = msg.get_payload(decode=True) or b""
+            charset = msg.get_content_charset() or "utf-8"
+            body_parts.append(payload.decode(charset, errors="replace"))
+
+    body_text = "\n".join([str(x) for x in body_parts if x is not None])
+
+    from_hdr = msg.get("From")
+    reply_to_hdr = msg.get("Reply-To")
+    to_hdr = msg.get("To")
+    subject = msg.get("Subject")
+    date = msg.get("Date")
+    authentication_results = msg.get("Authentication-Results")
+
+    from_domain = _extract_address_domain(from_hdr)
+    reply_to_domain = _extract_address_domain(reply_to_hdr)
+
+    urls = _extract_urls(body_text + "\n" + headers_text)
+
+    url_indicators = []
+    for u in urls:
+        host = _url_host(u)
+        host_type = "unknown"
+        if host:
+            if re.fullmatch(r"\d{1,3}(\.\d{1,3}){3}", host):
+                host_type = "ip_literal"
+            elif host.startswith("xn--"):
+                host_type = "punycode"
+            else:
+                host_type = "hostname"
+        url_indicators.append({
+            "url": u,
+            "host": host,
+            "host_type": host_type
+        })
+
+    indicators = {
+        "email": {
+            "from": from_hdr,
+            "from_domain": from_domain,
+            "reply_to": reply_to_hdr,
+            "reply_to_domain": reply_to_domain,
+            "to": to_hdr,
+            "subject": subject,
+            "date": date,
+            "authentication_results": authentication_results,
+        },
+        "received_lines": received_lines,
+        "urls": url_indicators
+    }
+
+    return {"indicators": indicators}

emlpeek-1.0.0/src/soc_email_investigator/main.py

@@ -0,0 +1,62 @@
+import argparse
+from pathlib import Path
+from datetime import datetime, timezone
+import json
+import hashlib
+
+from .extract import extract_from_eml
+from .rules import run_rules
+from .report import write_outputs
+
+
+TOOL_VERSION = "v1.0"
+TOOL_NAME = "emlpeek "
+
+def sha256_file(p: Path) -> str:
+    h = hashlib.sha256()
+    with p.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("input_path")
+    ap.add_argument("--out", required=True)
+    args = ap.parse_args()
+
+    in_path = Path(args.input_path)
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    eml_data = extract_from_eml(in_path)
+    signals = run_rules(eml_data)
+
+    evidence_manifest = {
+         "tool_name"     :TOOL_NAME,
+        "tool_version":   TOOL_VERSION,
+        "input": {
+            "path": str(in_path),
+            "filename": in_path.name,
+            "size_bytes": in_path.stat().st_size,
+            "sha256": sha256_file(in_path),
+        },
+        "run_utc": datetime.now(timezone.utc).isoformat()
+    }
+
+    write_outputs(
+        out_dir=out_dir,
+        indicators=eml_data["indicators"],
+        signals=signals,
+        verdict=signals["verdict"],
+        confidence=signals["confidence"],
+        report_context=signals["context"],
+        evidence_manifest=evidence_manifest,
+    )
+
+if __name__ == "__main__":
+    main()
+
+
+
+

emlpeek-1.0.0/src/soc_email_investigator/report.py

@@ -0,0 +1,59 @@
+import json
+from datetime import datetime, timezone
+
+def write_outputs(out_dir, indicators, signals, verdict, confidence, report_context, evidence_manifest):
+    # Save indicators
+    (out_dir / "indicators.json").write_text(
+        json.dumps(indicators, indent=2, ensure_ascii=False),
+        encoding="utf-8"
+    )
+
+    # Save signals
+    signals_out = {
+        "verdict": verdict,
+        "confidence": confidence,
+        "context": report_context
+    }
+    (out_dir / "signals.json").write_text(
+        json.dumps(signals_out, indent=2, ensure_ascii=False),
+        encoding="utf-8"
+    )
+
+    # Save evidence manifest
+    (out_dir / "evidence_manifest.json").write_text(
+        json.dumps(evidence_manifest, indent=2, ensure_ascii=False),
+        encoding="utf-8"
+    )
+
+    # Save report
+    run_utc = evidence_manifest.get("run_utc", "")
+    from_domain = indicators["email"].get("from_domain")
+    urls = indicators.get("urls", [])
+
+    lines = []
+    lines.append(f"# Email Investigation Report")
+    lines.append("")
+    lines.append(f"- **Verdict:** {verdict}")
+    lines.append(f"- **Confidence:** {confidence:.2f}")
+    if run_utc:
+        lines.append(f"- **Run (UTC):** {run_utc}")
+    lines.append("")
+    lines.append("## Key evidence")
+    lines.append(f"- From domain: {from_domain}")
+    lines.append(f"- URLs found: {len(urls)}")
+    if urls:
+        # list first few hosts/urls
+        for i, u in enumerate(urls[:10], start=1):
+            lines.append(f"  {i}. {u.get('url')} (host: {u.get('host')}, type: {u.get('host_type')})")
+    lines.append("")
+    lines.append("## Why this verdict")
+    if report_context:
+        for c in report_context:
+            lines.append(f"- {c}")
+    else:
+        lines.append("- (no context recorded)")
+    lines.append("")
+    lines.append("## Notes")
+    lines.append("- This is a rule-based system for v1 (it does not guarantee guilt/innocence).")
+
+    (out_dir / "report.md").write_text("\n".join(lines), encoding="utf-8")

emlpeek-1.0.0/src/soc_email_investigator/rules.py

@@ -0,0 +1,63 @@
+def run_rules(eml_data: dict) -> dict:
+    indicators = eml_data["indicators"]
+    email = indicators["email"]
+
+    urls = indicators.get("urls", [])
+    from_domain = email.get("from_domain")
+    reply_to_domain = email.get("reply_to_domain")
+
+    verdict = "uncertain"
+    confidence = 0.0
+    context = []
+
+    has_sender = bool(from_domain or reply_to_domain)
+    has_urls = len(urls) > 0
+
+    if not has_urls and not has_sender:
+        context.append("No URLs and no From/Reply-To domains found.")
+        return {"verdict": "uncertain", "confidence": 0.2, "context": context}
+
+    # choose base domain
+    base_domain = from_domain or reply_to_domain
+
+    # Rule 1: IP literal in URL => phishing
+    for u in urls:
+        if u.get("host_type") == "ip_literal":
+            verdict = "phishing"
+            confidence = 0.95
+            context.append(f"Found URL with IP-literal host: {u.get('host')}")
+            return {"verdict": verdict, "confidence": confidence, "context": context}
+
+    # Rule 2: suspicious host not related to sender domain (simple substring heuristic)
+    if has_urls and base_domain:
+        base = base_domain.lower()
+        for u in urls:
+            host = (u.get("host") or "").lower()
+            if not host:
+                continue
+            # if host doesn't share a substring with sender base domain, flag
+            if base not in host and host not in base:
+                verdict = "phishing"
+                confidence = 0.75
+                context.append(f"URL host {host} does not relate to sender domain {base}.")
+                break
+
+    # Rule 3: decide legit/uncertain if not phishing
+    if verdict != "phishing":
+        if has_urls and base_domain and len(context) == 0:
+            verdict = "legit"
+            confidence = 0.65
+            context.append("URLs found and no strong phishing indicators matched.")
+        else:
+            verdict = "uncertain"
+            confidence = 0.45
+            context.append("Not enough evidence to label as phishing/legit confidently.")
+
+    # Always record authentication-results presence (no guessing)
+    auth = email.get("authentication_results")
+    if auth:
+        context.append("Authentication-Results header is present (no pass/fail inferred).")
+    else:
+        context.append("Authentication-Results header not found (may reduce confidence).")
+
+    return {"verdict": verdict, "confidence": confidence, "context": context}