pcaptriage 0.1.0__tar.gz

pcaptriage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zakariya Elmansouri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pcaptriage-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: pcaptriage
+Version: 0.1.0
+Summary: Automated pcap triage on top of Zeek, with MITRE ATT&CK-mapped findings and an HTML report.
+Author-email: Zakariya Elmansouri <zakariyaelmansouri40@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zakeelm6/pcaptriage
+Project-URL: Repository, https://github.com/zakeelm6/pcaptriage
+Project-URL: Issues, https://github.com/zakeelm6/pcaptriage/issues
+Keywords: pcap,zeek,network-security,mitre-attack,threat-detection,incident-response,dfir,soc,forensics,pcap-analysis,triage,blue-team
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pcaptriage
+
+Triage automatique de captures reseau, construit au-dessus de **Zeek**.
+
+Wireshark est manuel : tu ouvres un pcap et tu cherches toi-meme. pcaptriage
+fait l'inverse. Il laisse Zeek parser les protocoles, puis il applique une
+couche de triage : il detecte des comportements suspects, les mappe sur
+**MITRE ATT&CK**, et sort un rapport HTML priorise plus un JSON automatisable.
+Pensé pour traiter un pcap (ou un dossier entier) en une commande et rendre un
+verdict lisible, pas pour remplacer le decodeur de Wireshark.
+
+## Ce qu'il detecte
+
+| Detection | Signal | MITRE |
+|---|---|---|
+| Credentials en clair | FTP/HTTP basic auth, services non chiffres | T1552, T1040 |
+| Scan de ports / hotes | une source touche beaucoup de ports/hotes, connexions non abouties | T1046 |
+| DNS tunneling / exfiltration | fort volume + noms longs/haute entropie vers un domaine | T1071.004, T1048 |
+| Beaconing / C2 | rappels a intervalle quasi constant vers une meme destination | T1071, T1095 |
+| Certificats TLS suspects | certificats auto-signes, expires ou non valides | T1573 |
+
+## Prerequis
+
+- **Python 3.9+** (teste sur 3.14). Aucune dependance pip, stdlib uniquement.
+- **Zeek**, au choix :
+  - local : `zeek` dans le PATH ;
+  - **Docker** (recommande sur Kali, ou le paquet .deb casse la libc) :
+    ```bash
+    docker pull zeek/zeek:lts
+    ```
+
+## Installation
+
+```bash
+# en tant que commande systeme (recommande, via pipx)
+pipx install git+https://github.com/zakeelm6/pcaptriage.git
+
+# ou avec pip, dans un venv
+pip install git+https://github.com/zakeelm6/pcaptriage.git
+
+# en developpement, depuis une copie locale
+pip install -e .
+```
+
+Une fois installe, la commande `pcaptriage` est disponible. Sans installation,
+tout marche aussi via `python3 -m pcaptriage`.
+
+## Usage
+
+```bash
+# un seul pcap, Zeek via Docker
+pcaptriage capture.pcap --docker
+
+# un dossier entier de captures
+python3 -m pcaptriage ./captures/ --docker -o resultats/
+
+# Zeek installe en local
+python3 -m pcaptriage capture.pcap
+```
+
+Sortie, par capture, dans le dossier `-o` (defaut `pcaptriage-report/`) :
+
+```
+pcaptriage-report/
+  <nom-capture>/
+    report.html      <- rapport lisible (clair/sombre), findings prioritises
+    findings.json    <- meme contenu, automatisable (injectable dans un SIEM)
+    zeek-logs/       <- logs Zeek bruts (conn/dns/http/ssl/...)
+```
+
+## Architecture
+
+```
+pcap --> Zeek (parsing) --> *.log JSON --> loader --> detections --> findings
+                                                          |             |
+                                                      MITRE map     report HTML + JSON
+```
+
+- `zeek_runner.py` lance Zeek (local ou Docker) et produit les logs JSON.
+- `loader.py` charge les logs en memoire.
+- `detections/` : une detection = une fonction decoree `@register` qui prend
+  les logs et renvoie des `Finding`. Ajouter une detection = ajouter un fichier.
+- `mitre.py` : table technique -> (nom, lien).
+- `report.py` : resume de la capture + rendu HTML autonome.
+- `cli.py` : orchestration, mode fichier ou dossier.
+
+## Feuille de route
+
+- ARP spoofing / MITM, LLMNR/NBT-NS poisoning
+- Extraction de fichiers (files.log) et de credentials additionnels
+- Moteur de regles externes (YAML/Sigma-like) pour etendre sans coder
+- Graphe de communication dans le rapport
+- Sortie directe vers Elasticsearch (lien avec Mini-SOC)
+
+## Note
+
+Outil d'analyse defensive / forensic sur des captures que tu es autorise a
+analyser. Les logs peuvent contenir des donnees sensibles (identifiants,
+hotes) : traite les sorties en consequence.

pcaptriage-0.1.0/README.md

@@ -0,0 +1,99 @@
+# pcaptriage
+
+Triage automatique de captures reseau, construit au-dessus de **Zeek**.
+
+Wireshark est manuel : tu ouvres un pcap et tu cherches toi-meme. pcaptriage
+fait l'inverse. Il laisse Zeek parser les protocoles, puis il applique une
+couche de triage : il detecte des comportements suspects, les mappe sur
+**MITRE ATT&CK**, et sort un rapport HTML priorise plus un JSON automatisable.
+Pensé pour traiter un pcap (ou un dossier entier) en une commande et rendre un
+verdict lisible, pas pour remplacer le decodeur de Wireshark.
+
+## Ce qu'il detecte
+
+| Detection | Signal | MITRE |
+|---|---|---|
+| Credentials en clair | FTP/HTTP basic auth, services non chiffres | T1552, T1040 |
+| Scan de ports / hotes | une source touche beaucoup de ports/hotes, connexions non abouties | T1046 |
+| DNS tunneling / exfiltration | fort volume + noms longs/haute entropie vers un domaine | T1071.004, T1048 |
+| Beaconing / C2 | rappels a intervalle quasi constant vers une meme destination | T1071, T1095 |
+| Certificats TLS suspects | certificats auto-signes, expires ou non valides | T1573 |
+
+## Prerequis
+
+- **Python 3.9+** (teste sur 3.14). Aucune dependance pip, stdlib uniquement.
+- **Zeek**, au choix :
+  - local : `zeek` dans le PATH ;
+  - **Docker** (recommande sur Kali, ou le paquet .deb casse la libc) :
+    ```bash
+    docker pull zeek/zeek:lts
+    ```
+
+## Installation
+
+```bash
+# en tant que commande systeme (recommande, via pipx)
+pipx install git+https://github.com/zakeelm6/pcaptriage.git
+
+# ou avec pip, dans un venv
+pip install git+https://github.com/zakeelm6/pcaptriage.git
+
+# en developpement, depuis une copie locale
+pip install -e .
+```
+
+Une fois installe, la commande `pcaptriage` est disponible. Sans installation,
+tout marche aussi via `python3 -m pcaptriage`.
+
+## Usage
+
+```bash
+# un seul pcap, Zeek via Docker
+pcaptriage capture.pcap --docker
+
+# un dossier entier de captures
+python3 -m pcaptriage ./captures/ --docker -o resultats/
+
+# Zeek installe en local
+python3 -m pcaptriage capture.pcap
+```
+
+Sortie, par capture, dans le dossier `-o` (defaut `pcaptriage-report/`) :
+
+```
+pcaptriage-report/
+  <nom-capture>/
+    report.html      <- rapport lisible (clair/sombre), findings prioritises
+    findings.json    <- meme contenu, automatisable (injectable dans un SIEM)
+    zeek-logs/       <- logs Zeek bruts (conn/dns/http/ssl/...)
+```
+
+## Architecture
+
+```
+pcap --> Zeek (parsing) --> *.log JSON --> loader --> detections --> findings
+                                                          |             |
+                                                      MITRE map     report HTML + JSON
+```
+
+- `zeek_runner.py` lance Zeek (local ou Docker) et produit les logs JSON.
+- `loader.py` charge les logs en memoire.
+- `detections/` : une detection = une fonction decoree `@register` qui prend
+  les logs et renvoie des `Finding`. Ajouter une detection = ajouter un fichier.
+- `mitre.py` : table technique -> (nom, lien).
+- `report.py` : resume de la capture + rendu HTML autonome.
+- `cli.py` : orchestration, mode fichier ou dossier.
+
+## Feuille de route
+
+- ARP spoofing / MITM, LLMNR/NBT-NS poisoning
+- Extraction de fichiers (files.log) et de credentials additionnels
+- Moteur de regles externes (YAML/Sigma-like) pour etendre sans coder
+- Graphe de communication dans le rapport
+- Sortie directe vers Elasticsearch (lien avec Mini-SOC)
+
+## Note
+
+Outil d'analyse defensive / forensic sur des captures que tu es autorise a
+analyser. Les logs peuvent contenir des donnees sensibles (identifiants,
+hotes) : traite les sorties en consequence.

pcaptriage-0.1.0/pcaptriage/__init__.py

@@ -0,0 +1,7 @@
+"""pcaptriage - automated pcap triage on top of Zeek.
+
+Zeek does the protocol parsing, this package adds the triage layer:
+detections mapped to MITRE ATT&CK, artifact extraction and a report.
+"""
+
+__version__ = "0.1.0"

pcaptriage-0.1.0/pcaptriage/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pcaptriage-0.1.0/pcaptriage/cli.py

@@ -0,0 +1,125 @@
+"""Command-line interface for pcaptriage."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List
+
+from . import __version__
+from .detections import all_detections
+from .loader import load_logs
+from .report import build_summary, render_html
+from .zeek_runner import ZeekError, run_zeek
+
+PCAP_EXTS = {".pcap", ".pcapng", ".cap"}
+
+
+def _analyze_one(pcap: Path, out_root: Path, args) -> int:
+    """Analyze a single pcap. Returns the number of findings."""
+    case_dir = out_root / pcap.stem
+    logs_dir = case_dir / "zeek-logs"
+    print(f"[*] {pcap.name}: running Zeek ({'docker' if args.docker else 'local'})...")
+    try:
+        run_zeek(
+            str(pcap),
+            str(logs_dir),
+            use_docker=args.docker,
+            zeek_cmd=args.zeek_cmd,
+            docker_image=args.docker_image,
+        )
+    except ZeekError as exc:
+        print(f"[!] {pcap.name}: {exc}", file=sys.stderr)
+        return -1
+
+    logs = load_logs(str(logs_dir))
+    findings = []
+    for detect in all_detections():
+        findings.extend(detect(logs))
+
+    summary = build_summary(logs)
+
+    report_path = case_dir / "report.html"
+    report_path.write_text(render_html(pcap.name, summary, findings), encoding="utf-8")
+
+    json_path = case_dir / "findings.json"
+    json_path.write_text(
+        json.dumps(
+            {
+                "pcap": pcap.name,
+                "summary": {k: v for k, v in summary.items()},
+                "findings": [f.to_dict() for f in findings],
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+    sev = {}
+    for f in findings:
+        sev[f.severity] = sev.get(f.severity, 0) + 1
+    sev_str = ", ".join(f"{v} {k}" for k, v in sorted(sev.items())) or "none"
+    print(f"[+] {pcap.name}: {len(findings)} finding(s) ({sev_str}) -> {report_path}")
+    return len(findings)
+
+
+def _collect_pcaps(target: Path) -> List[Path]:
+    if target.is_file():
+        return [target]
+    if target.is_dir():
+        return sorted(p for p in target.rglob("*") if p.suffix.lower() in PCAP_EXTS)
+    return []
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pcaptriage",
+        description="Automated pcap triage on top of Zeek, mapped to MITRE ATT&CK.",
+    )
+    parser.add_argument("target", help="a .pcap file or a directory of captures")
+    parser.add_argument(
+        "-o", "--output", default="pcaptriage-report",
+        help="output directory (default: ./pcaptriage-report)",
+    )
+    parser.add_argument(
+        "--docker", action="store_true",
+        help="run Zeek via Docker instead of a local install",
+    )
+    parser.add_argument(
+        "--zeek-cmd", default="zeek",
+        help="local Zeek binary name/path (default: zeek)",
+    )
+    parser.add_argument(
+        "--docker-image", default="zeek/zeek:lts",
+        help="Zeek Docker image (default: zeek/zeek:lts)",
+    )
+    parser.add_argument("--version", action="version", version=f"pcaptriage {__version__}")
+    args = parser.parse_args(argv)
+
+    target = Path(args.target)
+    pcaps = _collect_pcaps(target)
+    if not pcaps:
+        print(f"[!] no pcap found at: {target}", file=sys.stderr)
+        return 2
+
+    out_root = Path(args.output)
+    out_root.mkdir(parents=True, exist_ok=True)
+
+    total = 0
+    failures = 0
+    for pcap in pcaps:
+        n = _analyze_one(pcap, out_root, args)
+        if n < 0:
+            failures += 1
+        else:
+            total += n
+
+    print(f"\n[=] done: {len(pcaps) - failures}/{len(pcaps)} capture(s) analyzed, "
+          f"{total} finding(s) total. Reports in {out_root}/")
+    return 1 if failures and failures == len(pcaps) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pcaptriage-0.1.0/pcaptriage/detections/__init__.py

@@ -0,0 +1,13 @@
+"""Detection package.
+
+Importing this package registers all detections via the @register
+decorator in each module.
+"""
+
+from . import cleartext_creds  # noqa: F401
+from . import port_scan        # noqa: F401
+from . import dns_tunneling    # noqa: F401
+from . import beaconing        # noqa: F401
+from . import suspicious_tls   # noqa: F401
+
+from .base import all_detections, Finding  # noqa: F401

pcaptriage-0.1.0/pcaptriage/detections/base.py

@@ -0,0 +1,47 @@
+"""Finding model and detection registry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Callable, Dict, List
+
+SEVERITY_ORDER = {
+    "critical": 4,
+    "high": 3,
+    "medium": 2,
+    "low": 1,
+    "info": 0,
+}
+
+
+@dataclass
+class Finding:
+    id: str                      # stable slug, e.g. "cleartext-creds"
+    title: str
+    severity: str                # one of SEVERITY_ORDER keys
+    description: str
+    mitre: List[str] = field(default_factory=list)   # technique ids, e.g. ["T1110"]
+    evidence: List[str] = field(default_factory=list)
+    source_log: str = ""         # which Zeek log it came from
+
+    def severity_rank(self) -> int:
+        return SEVERITY_ORDER.get(self.severity, 0)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# A detection takes the loaded Zeek logs and returns zero or more findings.
+Detection = Callable[[Dict[str, List[dict]]], List[Finding]]
+
+_REGISTRY: List[Detection] = []
+
+
+def register(fn: Detection) -> Detection:
+    """Decorator to register a detection function."""
+    _REGISTRY.append(fn)
+    return fn
+
+
+def all_detections() -> List[Detection]:
+    return list(_REGISTRY)

pcaptriage-0.1.0/pcaptriage/detections/beaconing.py

@@ -0,0 +1,71 @@
+"""Detect regular beaconing to a destination (possible C2)."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from statistics import mean, pstdev
+from typing import Dict, List
+
+from .base import Finding, register
+
+# Minimum connections to the same destination to judge regularity.
+MIN_CONNECTIONS = 10
+# Coefficient of variation of inter-arrival times below this = very regular.
+CV_HIGH = 0.10
+CV_MEDIUM = 0.25
+
+
+@register
+def detect_beaconing(logs: Dict[str, List[dict]]) -> List[Finding]:
+    conns = logs.get("conn", [])
+    if not conns:
+        return []
+
+    # Group connection start times per (src, dst, dst_port).
+    times: Dict[tuple, List[float]] = defaultdict(list)
+    for rec in conns:
+        src = rec.get("id.orig_h")
+        dst = rec.get("id.resp_h")
+        port = rec.get("id.resp_p")
+        ts = rec.get("ts")
+        if src and dst and isinstance(ts, (int, float)):
+            times[(src, dst, port)].append(ts)
+
+    findings: List[Finding] = []
+    for (src, dst, port), ts_list in times.items():
+        if len(ts_list) < MIN_CONNECTIONS:
+            continue
+        ts_list.sort()
+        deltas = [b - a for a, b in zip(ts_list, ts_list[1:]) if b - a > 0]
+        if len(deltas) < MIN_CONNECTIONS - 1:
+            continue
+        m = mean(deltas)
+        if m <= 0:
+            continue
+        cv = pstdev(deltas) / m
+        if cv > CV_MEDIUM:
+            continue
+        severity = "high" if cv <= CV_HIGH else "medium"
+        findings.append(
+            Finding(
+                id="beaconing",
+                title=f"Regular beaconing {src} -> {dst}:{port}",
+                severity=severity,
+                description=(
+                    "A host contacted the same destination at a near-constant "
+                    "interval. Regular, automated callbacks are a common sign of "
+                    "command-and-control (C2) traffic."
+                ),
+                mitre=["T1071", "T1095"],
+                evidence=[
+                    f"source: {src}",
+                    f"destination: {dst}:{port}",
+                    f"connections: {len(ts_list)}",
+                    f"mean interval: {m:.1f} s",
+                    f"interval regularity (CV): {cv:.3f} (lower = more regular)",
+                ],
+                source_log="conn",
+            )
+        )
+
+    return findings

pcaptriage-0.1.0/pcaptriage/detections/cleartext_creds.py

@@ -0,0 +1,84 @@
+"""Detect credentials sent over cleartext protocols."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .base import Finding, register
+
+# Ports/services that carry credentials without encryption.
+CLEARTEXT_SERVICES = {
+    21: "FTP",
+    23: "Telnet",
+    80: "HTTP",
+    110: "POP3",
+    143: "IMAP",
+    25: "SMTP",
+}
+
+
+@register
+def detect_cleartext_creds(logs: Dict[str, List[dict]]) -> List[Finding]:
+    findings: List[Finding] = []
+    evidence: List[str] = []
+
+    # FTP: Zeek ftp.log carries 'user' and 'password'.
+    for rec in logs.get("ftp", []):
+        user = rec.get("user")
+        pw = rec.get("password")
+        if user:
+            src = rec.get("id.orig_h", "?")
+            dst = rec.get("id.resp_h", "?")
+            shown_pw = pw if pw else "(captured)"
+            evidence.append(f"FTP {src} -> {dst} login user={user} password={shown_pw}")
+
+    # HTTP basic auth: Zeek http.log exposes 'username' (and 'password').
+    for rec in logs.get("http", []):
+        user = rec.get("username")
+        if user:
+            src = rec.get("id.orig_h", "?")
+            host = rec.get("host", rec.get("id.resp_h", "?"))
+            uri = rec.get("uri", "")
+            evidence.append(f"HTTP basic auth {src} -> {host}{uri} user={user}")
+
+    # Any session on a cleartext service, from conn.log (coarse signal).
+    cleartext_sessions = 0
+    for rec in logs.get("conn", []):
+        port = rec.get("id.resp_p")
+        if port in CLEARTEXT_SERVICES:
+            cleartext_sessions += 1
+
+    if evidence:
+        findings.append(
+            Finding(
+                id="cleartext-creds",
+                title="Credentials transmitted in cleartext",
+                severity="high",
+                description=(
+                    "Login credentials were observed over an unencrypted protocol. "
+                    "Anyone on the path can capture them. Move the service to a "
+                    "TLS-protected equivalent (FTPS/SFTP, HTTPS, IMAPS...)."
+                ),
+                mitre=["T1552", "T1040"],
+                evidence=evidence[:25],
+                source_log="ftp/http",
+            )
+        )
+    elif cleartext_sessions:
+        findings.append(
+            Finding(
+                id="cleartext-services",
+                title="Cleartext services in use",
+                severity="low",
+                description=(
+                    f"{cleartext_sessions} session(s) used a cleartext protocol "
+                    "(FTP/Telnet/HTTP/POP3/IMAP/SMTP). No credentials were parsed, "
+                    "but traffic is exposed to sniffing."
+                ),
+                mitre=["T1040"],
+                evidence=[],
+                source_log="conn",
+            )
+        )
+
+    return findings

pcaptriage-0.1.0/pcaptriage/detections/dns_tunneling.py

@@ -0,0 +1,85 @@
+"""Detect possible DNS tunneling / exfiltration from dns.log."""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from typing import Dict, List
+
+from .base import Finding, register
+
+# A registered domain seen more than this many times is worth a look.
+QUERY_COUNT_THRESHOLD = 100
+# Average queried-name length above this suggests encoded data.
+AVG_LEN_THRESHOLD = 40
+# Shannon entropy above this suggests encoded/compressed subdomains.
+ENTROPY_THRESHOLD = 3.5
+
+
+def _entropy(s: str) -> float:
+    if not s:
+        return 0.0
+    counts: Dict[str, int] = {}
+    for ch in s:
+        counts[ch] = counts.get(ch, 0) + 1
+    n = len(s)
+    return -sum((c / n) * math.log2(c / n) for c in counts.values())
+
+
+def _registered_domain(qname: str) -> str:
+    """Rough eTLD+1: last two labels. Good enough for triage."""
+    labels = qname.rstrip(".").split(".")
+    return ".".join(labels[-2:]) if len(labels) >= 2 else qname
+
+
+@register
+def detect_dns_tunneling(logs: Dict[str, List[dict]]) -> List[Finding]:
+    dns = logs.get("dns", [])
+    if not dns:
+        return []
+
+    count_by_domain: Dict[str, int] = defaultdict(int)
+    len_sum_by_domain: Dict[str, int] = defaultdict(int)
+    ent_sum_by_domain: Dict[str, float] = defaultdict(float)
+
+    for rec in dns:
+        qname = rec.get("query")
+        if not qname:
+            continue
+        dom = _registered_domain(qname)
+        # Measure the part below the registered domain (the subdomain).
+        sub = qname[: -len(dom)].rstrip(".") if qname.endswith(dom) else qname
+        count_by_domain[dom] += 1
+        len_sum_by_domain[dom] += len(qname)
+        ent_sum_by_domain[dom] += _entropy(sub)
+
+    findings: List[Finding] = []
+    for dom, count in sorted(count_by_domain.items(), key=lambda kv: kv[1], reverse=True):
+        if count < QUERY_COUNT_THRESHOLD:
+            continue
+        avg_len = len_sum_by_domain[dom] / count
+        avg_ent = ent_sum_by_domain[dom] / count
+        if avg_len >= AVG_LEN_THRESHOLD or avg_ent >= ENTROPY_THRESHOLD:
+            severity = "high" if (avg_len >= AVG_LEN_THRESHOLD and avg_ent >= ENTROPY_THRESHOLD) else "medium"
+            findings.append(
+                Finding(
+                    id="dns-tunneling",
+                    title=f"Possible DNS tunneling via {dom}",
+                    severity=severity,
+                    description=(
+                        "A single domain received a high volume of queries with long "
+                        "and/or high-entropy names. This pattern is consistent with "
+                        "data encoded into DNS (tunneling or exfiltration)."
+                    ),
+                    mitre=["T1071.004", "T1048"],
+                    evidence=[
+                        f"domain: {dom}",
+                        f"query count: {count}",
+                        f"average query length: {avg_len:.1f}",
+                        f"average subdomain entropy: {avg_ent:.2f}",
+                    ],
+                    source_log="dns",
+                )
+            )
+
+    return findings