pcaptriage 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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/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/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/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/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

pcaptriage/detections/port_scan.py

@@ -0,0 +1,74 @@
+"""Detect port/host scanning from conn.log."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Dict, List, Set
+
+from .base import Finding, register
+
+# A source touching this many distinct destination ports looks like a scan.
+PORT_THRESHOLD = 50
+# A source touching this many distinct hosts looks like a sweep.
+HOST_THRESHOLD = 25
+# Connection states typical of scans (no payload / rejected / reset).
+SCAN_STATES = {"S0", "REJ", "RSTR", "RSTOS0", "SH", "OTH"}
+
+
+@register
+def detect_port_scan(logs: Dict[str, List[dict]]) -> List[Finding]:
+    conns = logs.get("conn", [])
+    if not conns:
+        return []
+
+    ports_by_src: Dict[str, Set[int]] = defaultdict(set)
+    hosts_by_src: Dict[str, Set[str]] = defaultdict(set)
+    scanlike_by_src: Dict[str, int] = defaultdict(int)
+
+    for rec in conns:
+        src = rec.get("id.orig_h")
+        dst = rec.get("id.resp_h")
+        port = rec.get("id.resp_p")
+        state = rec.get("conn_state", "")
+        if src is None:
+            continue
+        if port is not None:
+            ports_by_src[src].add(port)
+        if dst is not None:
+            hosts_by_src[src].add(dst)
+        if state in SCAN_STATES:
+            scanlike_by_src[src] += 1
+
+    findings: List[Finding] = []
+    for src in sorted(ports_by_src, key=lambda s: len(ports_by_src[s]), reverse=True):
+        n_ports = len(ports_by_src[src])
+        n_hosts = len(hosts_by_src[src])
+        n_scanlike = scanlike_by_src.get(src, 0)
+
+        if n_ports >= PORT_THRESHOLD or n_hosts >= HOST_THRESHOLD:
+            evidence = [
+                f"source {src}",
+                f"distinct destination ports: {n_ports}",
+                f"distinct destination hosts: {n_hosts}",
+                f"scan-like connection states (S0/REJ/RST...): {n_scanlike}",
+            ]
+            severity = "medium"
+            if n_ports >= PORT_THRESHOLD and n_scanlike > n_ports // 2:
+                severity = "high"
+            findings.append(
+                Finding(
+                    id="port-scan",
+                    title=f"Port/host scan from {src}",
+                    severity=severity,
+                    description=(
+                        "A single source contacted an unusually large number of "
+                        "ports or hosts, with many connections never completing. "
+                        "This is consistent with network/service discovery."
+                    ),
+                    mitre=["T1046"],
+                    evidence=evidence,
+                    source_log="conn",
+                )
+            )
+
+    return findings

pcaptriage/detections/suspicious_tls.py

@@ -0,0 +1,65 @@
+"""Flag suspicious TLS certificates from ssl.log."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Dict, List
+
+from .base import Finding, register
+
+# Validation outcomes Zeek reports that are not a clean, trusted chain.
+BAD_STATUSES = {
+    "self signed certificate",
+    "self signed certificate in certificate chain",
+    "unable to get local issuer certificate",
+    "certificate has expired",
+    "unable to verify the first certificate",
+}
+
+
+@register
+def detect_suspicious_tls(logs: Dict[str, List[dict]]) -> List[Finding]:
+    ssl = logs.get("ssl", [])
+    if not ssl:
+        return []
+
+    evidence: List[str] = []
+    reasons: Counter = Counter()
+
+    for rec in ssl:
+        status = (rec.get("validation_status") or "").lower()
+        subject = rec.get("subject", "")
+        server = rec.get("server_name", "")
+        dst = rec.get("id.resp_h", "?")
+        dport = rec.get("id.resp_p", "?")
+        if status and status != "ok" and (status in BAD_STATUSES or "self signed" in status or "expired" in status):
+            reasons[status] += 1
+            label = server or subject or "(no SNI/subject)"
+            evidence.append(f"{dst}:{dport} {label} -> {status}")
+
+    if not evidence:
+        return []
+
+    # Self-signed on an unusual port is a stronger C2 signal than a plain
+    # expired cert on 443.
+    severity = "medium"
+    if any("self signed" in r for r in reasons):
+        severity = "high"
+
+    reason_summary = ", ".join(f"{n}x {r}" for r, n in reasons.most_common())
+    return [
+        Finding(
+            id="suspicious-tls",
+            title="Suspicious TLS certificate(s)",
+            severity=severity,
+            description=(
+                "One or more TLS sessions used certificates that do not validate "
+                "against a trusted chain (self-signed, expired, or unknown issuer). "
+                "Benign in internal/dev setups, but also typical of malware C2 and "
+                "interception. Summary: " + reason_summary
+            ),
+            mitre=["T1573"],
+            evidence=evidence[:25],
+            source_log="ssl",
+        )
+    ]

pcaptriage/loader.py

@@ -0,0 +1,32 @@
+"""Load Zeek JSON logs into memory."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List
+
+
+def load_logs(logs_dir: str) -> Dict[str, List[dict]]:
+    """Read every *.log file in `logs_dir` as JSON lines.
+
+    Returns a mapping: log name without extension -> list of records.
+    e.g. {"conn": [...], "dns": [...], "http": [...]}.
+    Lines that fail to parse are skipped (Zeek can emit a non-JSON
+    header on some logs depending on version/config).
+    """
+    logs: Dict[str, List[dict]] = {}
+    for path in sorted(Path(logs_dir).glob("*.log")):
+        name = path.stem
+        records: List[dict] = []
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+        logs[name] = records
+    return logs

pcaptriage/mitre.py

@@ -0,0 +1,28 @@
+"""Minimal MITRE ATT&CK technique lookup used by detections."""
+
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+# technique id -> (name, url)
+TECHNIQUES: Dict[str, Tuple[str, str]] = {
+    "T1046": ("Network Service Discovery", "https://attack.mitre.org/techniques/T1046/"),
+    "T1040": ("Network Sniffing", "https://attack.mitre.org/techniques/T1040/"),
+    "T1110": ("Brute Force", "https://attack.mitre.org/techniques/T1110/"),
+    "T1552": ("Unsecured Credentials", "https://attack.mitre.org/techniques/T1552/"),
+    "T1071": ("Application Layer Protocol", "https://attack.mitre.org/techniques/T1071/"),
+    "T1071.004": ("Application Layer Protocol: DNS", "https://attack.mitre.org/techniques/T1071/004/"),
+    "T1095": ("Non-Application Layer Protocol", "https://attack.mitre.org/techniques/T1095/"),
+    "T1573": ("Encrypted Channel", "https://attack.mitre.org/techniques/T1573/"),
+    "T1048": ("Exfiltration Over Alternative Protocol", "https://attack.mitre.org/techniques/T1048/"),
+    "T1557.001": ("Adversary-in-the-Middle: LLMNR/NBT-NS Poisoning", "https://attack.mitre.org/techniques/T1557/001/"),
+    "T1557": ("Adversary-in-the-Middle", "https://attack.mitre.org/techniques/T1557/"),
+}
+
+
+def describe(technique_id: str) -> Tuple[str, str]:
+    """Return (name, url) for a technique id, with a safe fallback."""
+    return TECHNIQUES.get(
+        technique_id,
+        (technique_id, f"https://attack.mitre.org/techniques/{technique_id.replace('.', '/')}/"),
+    )

pcaptriage/report.py

@@ -0,0 +1,199 @@
+"""Build the summary and render the HTML report."""
+
+from __future__ import annotations
+
+import html
+from collections import Counter
+from datetime import datetime, timezone
+from typing import Dict, List
+
+from .detections.base import Finding, SEVERITY_ORDER
+from .mitre import describe
+
+SEVERITY_COLORS = {
+    "critical": "#b4232a",
+    "high": "#d1495b",
+    "medium": "#e08a1e",
+    "low": "#3a7ca5",
+    "info": "#6c757d",
+}
+
+
+def build_summary(logs: Dict[str, List[dict]]) -> dict:
+    """Compute high-level stats from conn.log."""
+    conns = logs.get("conn", [])
+    talkers: Counter = Counter()
+    services: Counter = Counter()
+    hosts = set()
+    ts_values = []
+
+    for rec in conns:
+        src = rec.get("id.orig_h")
+        dst = rec.get("id.resp_h")
+        if src:
+            talkers[src] += 1
+            hosts.add(src)
+        if dst:
+            hosts.add(dst)
+        svc = rec.get("service") or f"port/{rec.get('id.resp_p')}"
+        services[svc] += 1
+        ts = rec.get("ts")
+        if isinstance(ts, (int, float)):
+            ts_values.append(ts)
+
+    span = ""
+    if ts_values:
+        start = datetime.fromtimestamp(min(ts_values), tz=timezone.utc)
+        end = datetime.fromtimestamp(max(ts_values), tz=timezone.utc)
+        span = f"{start.isoformat()} to {end.isoformat()}"
+
+    return {
+        "connections": len(conns),
+        "distinct_hosts": len(hosts),
+        "log_types": sorted(logs.keys()),
+        "top_talkers": talkers.most_common(10),
+        "top_services": services.most_common(10),
+        "time_span": span,
+    }
+
+
+def _esc(x) -> str:
+    return html.escape(str(x))
+
+
+def _finding_card(f: Finding) -> str:
+    color = SEVERITY_COLORS.get(f.severity, "#6c757d")
+    mitre_html = " ".join(
+        f'<a class="mitre" href="{_esc(describe(t)[1])}" target="_blank" rel="noopener">'
+        f"{_esc(t)} {_esc(describe(t)[0])}</a>"
+        for t in f.mitre
+    )
+    evidence_html = ""
+    if f.evidence:
+        items = "".join(f"<li><code>{_esc(e)}</code></li>" for e in f.evidence)
+        evidence_html = f"<details><summary>Evidence ({len(f.evidence)})</summary><ul>{items}</ul></details>"
+    return f"""
+    <article class="finding" style="--sev:{color}">
+      <header>
+        <span class="badge" style="background:{color}">{_esc(f.severity.upper())}</span>
+        <h3>{_esc(f.title)}</h3>
+      </header>
+      <p>{_esc(f.description)}</p>
+      <div class="mitre-row">{mitre_html}</div>
+      {evidence_html}
+      <footer>source: {_esc(f.source_log)}</footer>
+    </article>
+    """
+
+
+def render_html(pcap_name: str, summary: dict, findings: List[Finding]) -> str:
+    findings = sorted(findings, key=lambda f: f.severity_rank(), reverse=True)
+    counts = Counter(f.severity for f in findings)
+
+    sev_tiles = "".join(
+        f'<div class="tile" style="border-color:{SEVERITY_COLORS[s]}">'
+        f'<span class="n">{counts.get(s, 0)}</span><span class="l">{s}</span></div>'
+        for s in ("critical", "high", "medium", "low", "info")
+    )
+
+    talkers_rows = "".join(
+        f"<tr><td><code>{_esc(h)}</code></td><td>{n}</td></tr>" for h, n in summary["top_talkers"]
+    )
+    services_rows = "".join(
+        f"<tr><td>{_esc(s)}</td><td>{n}</td></tr>" for s, n in summary["top_services"]
+    )
+    findings_html = "".join(_finding_card(f) for f in findings) or (
+        '<p class="empty">No findings. Either the capture is clean, or the '
+        "patterns are outside the current detection set.</p>"
+    )
+
+    generated = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>pcaptriage report</title>
+<style>
+  :root {{
+    --bg:#f6f7f9; --card:#ffffff; --fg:#1b1f24; --muted:#5a6672;
+    --line:#e2e6ea; --accent:#19375f;
+  }}
+  @media (prefers-color-scheme: dark) {{
+    :root {{
+      --bg:#14171c; --card:#1d222a; --fg:#e8ecf1; --muted:#9aa5b1;
+      --line:#2b323c; --accent:#7fa8d8;
+    }}
+  }}
+  * {{ box-sizing:border-box; }}
+  body {{ margin:0; background:var(--bg); color:var(--fg);
+    font:15px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif; }}
+  .wrap {{ max-width:960px; margin:0 auto; padding:24px 16px 64px; }}
+  h1 {{ font-size:22px; margin:0 0 4px; }}
+  .sub {{ color:var(--muted); font-size:13px; margin-bottom:20px; }}
+  .tiles {{ display:flex; gap:10px; flex-wrap:wrap; margin:16px 0 28px; }}
+  .tile {{ background:var(--card); border:1px solid var(--line);
+    border-left-width:5px; border-radius:8px; padding:10px 16px; min-width:92px; }}
+  .tile .n {{ display:block; font-size:24px; font-weight:700; }}
+  .tile .l {{ display:block; font-size:11px; text-transform:uppercase;
+    letter-spacing:.06em; color:var(--muted); }}
+  section {{ margin:28px 0; }}
+  .grid {{ display:grid; grid-template-columns:1fr 1fr; gap:20px; }}
+  @media (max-width:640px) {{ .grid {{ grid-template-columns:1fr; }} }}
+  table {{ width:100%; border-collapse:collapse; background:var(--card);
+    border:1px solid var(--line); border-radius:8px; overflow:hidden; }}
+  th,td {{ text-align:left; padding:7px 12px; border-bottom:1px solid var(--line); font-size:13px; }}
+  th {{ color:var(--muted); font-weight:600; }}
+  tr:last-child td {{ border-bottom:none; }}
+  .finding {{ background:var(--card); border:1px solid var(--line);
+    border-left:5px solid var(--sev); border-radius:8px; padding:14px 16px; margin:14px 0; }}
+  .finding header {{ display:flex; align-items:center; gap:10px; }}
+  .finding h3 {{ margin:0; font-size:16px; }}
+  .badge {{ color:#fff; font-size:11px; font-weight:700; padding:2px 8px;
+    border-radius:4px; letter-spacing:.04em; }}
+  .mitre-row {{ margin:8px 0; display:flex; gap:8px; flex-wrap:wrap; }}
+  a.mitre {{ font-size:12px; text-decoration:none; color:var(--accent);
+    border:1px solid var(--accent); border-radius:4px; padding:1px 7px; }}
+  details {{ margin-top:8px; }}
+  summary {{ cursor:pointer; color:var(--muted); font-size:13px; }}
+  ul {{ margin:8px 0; padding-left:18px; }}
+  code {{ font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;
+    background:rgba(127,127,127,.12); padding:1px 5px; border-radius:4px; word-break:break-all; }}
+  .finding footer {{ margin-top:8px; color:var(--muted); font-size:11px; }}
+  .empty {{ color:var(--muted); }}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>pcaptriage report</h1>
+  <div class="sub">capture: <code>{_esc(pcap_name)}</code> &middot; generated {generated}</div>
+
+  <div class="tiles">{sev_tiles}</div>
+
+  <section>
+    <h2>Findings</h2>
+    {findings_html}
+  </section>
+
+  <section>
+    <h2>Capture summary</h2>
+    <p class="sub">{summary['connections']} connections &middot;
+      {summary['distinct_hosts']} distinct hosts &middot;
+      logs: {_esc(', '.join(summary['log_types']))}<br>
+      {_esc(summary['time_span'])}</p>
+    <div class="grid">
+      <div>
+        <h3>Top talkers</h3>
+        <table><tr><th>Host</th><th>Conns</th></tr>{talkers_rows}</table>
+      </div>
+      <div>
+        <h3>Top services</h3>
+        <table><tr><th>Service</th><th>Conns</th></tr>{services_rows}</table>
+      </div>
+    </div>
+  </section>
+</div>
+</body>
+</html>
+"""

pcaptriage/zeek_runner.py

@@ -0,0 +1,79 @@
+"""Run Zeek over a pcap and produce JSON logs.
+
+Zeek is the parsing engine. It can run either from a local install or
+inside Docker (default on systems where the distro package is broken,
+e.g. Kali where the zeek .deb conflicts with a newer libc6).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class ZeekError(RuntimeError):
+    pass
+
+
+def run_zeek(
+    pcap_path: str,
+    logs_dir: str,
+    use_docker: bool = False,
+    zeek_cmd: str = "zeek",
+    docker_image: str = "zeek/zeek:lts",
+) -> str:
+    """Run Zeek on `pcap_path`, writing JSON logs into `logs_dir`.
+
+    Returns the logs directory path. Raises ZeekError on failure.
+    """
+    pcap = Path(pcap_path).resolve()
+    if not pcap.is_file():
+        raise ZeekError(f"pcap not found: {pcap}")
+
+    out = Path(logs_dir).resolve()
+    out.mkdir(parents=True, exist_ok=True)
+
+    if use_docker:
+        # Mount the pcap's directory read-only and the logs dir as the
+        # working directory so Zeek writes its *.log files onto the host.
+        cmd = [
+            "docker", "run", "--rm",
+            "-v", f"{pcap.parent}:/pcap:ro",
+            "-v", f"{out}:/work",
+            "-w", "/work",
+            docker_image,
+            "zeek", "-C", "-r", f"/pcap/{pcap.name}", "LogAscii::use_json=T",
+        ]
+    else:
+        if shutil.which(zeek_cmd) is None:
+            raise ZeekError(
+                f"'{zeek_cmd}' not found on PATH. Install Zeek or use --docker."
+            )
+        cmd = [zeek_cmd, "-C", "-r", str(pcap), "LogAscii::use_json=T"]
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=str(out) if not use_docker else None,
+            capture_output=True,
+            text=True,
+            timeout=600,
+        )
+    except FileNotFoundError as exc:
+        raise ZeekError(f"could not launch Zeek ({exc})") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise ZeekError("Zeek timed out (capture too large?)") from exc
+
+    # Zeek prints parse warnings to stderr but still exits 0; only fail
+    # when no log was produced.
+    produced = list(out.glob("*.log"))
+    if proc.returncode != 0 and not produced:
+        raise ZeekError(
+            f"Zeek failed (exit {proc.returncode}).\n{proc.stderr.strip()}"
+        )
+    if not produced:
+        raise ZeekError("Zeek produced no logs (empty or unsupported capture).")
+
+    return str(out)

pcaptriage-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+pcaptriage/__init__.py,sha256=kwOZrV6tBULHrLOwrEMP3BfgsSr8JIMjPIhGVG8VD3c,219
+pcaptriage/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+pcaptriage/cli.py,sha256=Hb60sa_oqATHYSSPB3Ads0L4OS5JQVQJNbB4DN0f3G8,3785
+pcaptriage/loader.py,sha256=BS0zlhPk135MAPbPTnl0BfLdfLL2CSdrqTRsyZio9Dw,1072
+pcaptriage/mitre.py,sha256=AwwCsENvgg66FrQ4jEiUAKH7xDnNkGC49y8lY66rRhM,1502
+pcaptriage/report.py,sha256=nzGEUux7f18_vgaKoWGlVtexz97kcL83nLnsij1DTkk,7221
+pcaptriage/zeek_runner.py,sha256=b5oh-_ZvUp2LBjAhAmT-rWVlqrOr1cYth6NmdVpXHag,2434
+pcaptriage/detections/__init__.py,sha256=mon2By8YlfwinOw2CwGnD-oSJ68_IcmKzxL-VYEtoRI,397
+pcaptriage/detections/base.py,sha256=UX7pXNQ9M7-DUuanbqz_KL7vO8hI_OS6eSBdkoZwx_8,1199
+pcaptriage/detections/beaconing.py,sha256=dM5UxVwWY4rqhktG-I6RGtLezSYeKnEsAiYqN41WrKE,2367
+pcaptriage/detections/cleartext_creds.py,sha256=yXt9HdWqxiypF_SgsjnNf5CpYTZ5RK8PMLLINokQUng,2780
+pcaptriage/detections/dns_tunneling.py,sha256=9oQaTvm2-f_-DT9fcwuLPBNkXvYEp88h0ST8tmUrs6U,3083
+pcaptriage/detections/port_scan.py,sha256=Kcua8frTyvnbBSIEGxfPJnfHPcIMK9-exG2BvQr9VxA,2621
+pcaptriage/detections/suspicious_tls.py,sha256=8DBAddVp0TdgX3UfgVSAeXijSZ3ZLsRdtIUvvsgp-B4,2155
+pcaptriage-0.1.0.dist-info/licenses/LICENSE,sha256=2FDx1J9xeI2Vul5jJXBDZWFVjhfnL6aySrIXEnqNp3E,1076
+pcaptriage-0.1.0.dist-info/METADATA,sha256=JuuwF9hUBsDYnMzUSa5whqTm3Gc52zznVzw_l5MVPgE,4663
+pcaptriage-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pcaptriage-0.1.0.dist-info/entry_points.txt,sha256=CDZeVXDNXjZU8r_vCBRv1aFul_j00vPlTNxuy9nPJWU,51
+pcaptriage-0.1.0.dist-info/top_level.txt,sha256=DUzRZv438urQOpUUq7HCfXF3flkcz47BwYkjJSOrM04,11
+pcaptriage-0.1.0.dist-info/RECORD,,

pcaptriage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pcaptriage-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pcaptriage = pcaptriage.cli:main

pcaptriage-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pcaptriage