feat(prober-cert): capture leaf TLS cert after successful JARM
JARM probes are crafted ClientHellos with weird ciphers — they never complete a real handshake, so the peer cert isn't reachable from those sockets. After a non-empty JARM hash proves the port speaks TLS, do a separate ssl.wrap_socket() against the same (ip, port) to fetch and parse the leaf cert. - decnet/prober/tlscert.py: fetch + parse via cryptography lib; swallows all connect/handshake/parse failures (returns None). - decnet/prober/worker.py::_capture_tls_cert: emits a tls_certificate event with subject_cn / issuer / SANs / validity / SHA-256 + publishes on the bus. Wired from _jarm_phase only when JARM succeeds, so non-TLS ports never trigger a second connect. - Tests cover happy path, cert-fetch failure, defense-in-depth crash, empty-JARM skip, publish_fn, and parser edge cases (garbage DER, empty bytes, missing SAN extension, non-self-signed).
This commit is contained in:
131
decnet/prober/tlscert.py
Normal file
131
decnet/prober/tlscert.py
Normal file
@@ -0,0 +1,131 @@
|
||||
"""
|
||||
TLS leaf-certificate capture from attacker-run servers.
|
||||
|
||||
Companion to ``decnet.prober.jarm``: JARM probes are crafted ClientHellos
|
||||
that never complete a real handshake (raw byte parsing only), so the
|
||||
peer certificate is never available from those sockets. This module does
|
||||
a separate :func:`ssl.wrap_socket` against the same ``(host, port)``
|
||||
solely to fetch and parse the leaf cert.
|
||||
|
||||
The cert is intentionally NOT verified — attacker-presented certs are
|
||||
inherently untrusted, and rejecting self-signed ones would defeat the
|
||||
whole point of the capture (most C2 infra runs self-signed certs).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import socket
|
||||
import ssl
|
||||
from typing import Any
|
||||
|
||||
from cryptography import x509
|
||||
from cryptography.hazmat.backends import default_backend
|
||||
from cryptography.x509.oid import NameOID
|
||||
|
||||
from decnet.telemetry import traced as _traced
|
||||
|
||||
|
||||
def _cn_or_empty(name: x509.Name) -> str:
|
||||
"""Return the first CN attribute as a plain string, or ``""``."""
|
||||
attrs = name.get_attributes_for_oid(NameOID.COMMON_NAME)
|
||||
if not attrs:
|
||||
return ""
|
||||
return str(attrs[0].value)
|
||||
|
||||
|
||||
def _iso_utc(dt: Any) -> str:
|
||||
"""Cert validity timestamps as ``YYYY-MM-DDTHH:MM:SSZ``.
|
||||
|
||||
``cryptography`` exposes ``not_valid_before`` (deprecated, naive UTC)
|
||||
and ``not_valid_before_utc`` (timezone-aware) — prefer the latter
|
||||
when available so we always emit explicit-Z ISO strings.
|
||||
"""
|
||||
return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
def _extract_sans(cert: x509.Certificate) -> list[str]:
|
||||
"""All DNS / IP SANs as a flat list of strings; empty when absent."""
|
||||
try:
|
||||
ext = cert.extensions.get_extension_for_class(
|
||||
x509.SubjectAlternativeName
|
||||
)
|
||||
except x509.ExtensionNotFound:
|
||||
return []
|
||||
sans: list[str] = []
|
||||
san: x509.SubjectAlternativeName = ext.value
|
||||
sans.extend(str(v) for v in san.get_values_for_type(x509.DNSName))
|
||||
sans.extend(str(v) for v in san.get_values_for_type(x509.IPAddress))
|
||||
return sans
|
||||
|
||||
|
||||
@_traced("prober.tls_cert_parse")
|
||||
def parse_leaf_cert(der: bytes) -> dict[str, Any] | None:
|
||||
"""Parse a DER-encoded leaf cert into the prober's flat field shape.
|
||||
|
||||
Returns ``None`` if parsing fails for any reason — the caller treats
|
||||
that the same as a connect failure.
|
||||
"""
|
||||
try:
|
||||
cert = x509.load_der_x509_certificate(der, default_backend())
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
try:
|
||||
subject_cn = _cn_or_empty(cert.subject)
|
||||
issuer = cert.issuer.rfc4514_string()
|
||||
issuer_cn = _cn_or_empty(cert.issuer)
|
||||
try:
|
||||
nb = cert.not_valid_before_utc
|
||||
na = cert.not_valid_after_utc
|
||||
except AttributeError: # cryptography < 42
|
||||
nb = cert.not_valid_before
|
||||
na = cert.not_valid_after
|
||||
not_before = _iso_utc(nb)
|
||||
not_after = _iso_utc(na)
|
||||
self_signed = bool(subject_cn) and subject_cn == issuer_cn
|
||||
sans = _extract_sans(cert)
|
||||
cert_sha256 = hashlib.sha256(der).hexdigest()
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
return {
|
||||
"subject_cn": subject_cn,
|
||||
"issuer": issuer,
|
||||
"self_signed": self_signed,
|
||||
"not_before": not_before,
|
||||
"not_after": not_after,
|
||||
"sans": sans,
|
||||
"cert_sha256": cert_sha256,
|
||||
}
|
||||
|
||||
|
||||
@_traced("prober.tls_cert_fetch")
|
||||
def fetch_leaf_cert(
|
||||
host: str, port: int, timeout: float = 5.0
|
||||
) -> dict[str, Any] | None:
|
||||
"""Open a TLS connection and return the parsed leaf cert.
|
||||
|
||||
Returns ``None`` on any connect / handshake / parse failure. Never
|
||||
raises — failures must collapse silently so the prober's outer loop
|
||||
can keep moving through targets.
|
||||
"""
|
||||
ctx = ssl.create_default_context()
|
||||
ctx.check_hostname = False
|
||||
ctx.verify_mode = ssl.CERT_NONE
|
||||
# Some attacker C2 servers gate on weak ciphers; don't constrain.
|
||||
ctx.set_ciphers("ALL:@SECLEVEL=0")
|
||||
|
||||
try:
|
||||
with socket.create_connection((host, port), timeout=timeout) as raw:
|
||||
raw.settimeout(timeout)
|
||||
with ctx.wrap_socket(raw, server_hostname=None) as tls:
|
||||
der = tls.getpeercert(binary_form=True)
|
||||
except (OSError, ssl.SSLError, socket.timeout):
|
||||
return None
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
if not der:
|
||||
return None
|
||||
return parse_leaf_cert(der)
|
||||
@@ -39,6 +39,7 @@ from decnet.logging import get_logger
|
||||
from decnet.prober.hassh import hassh_server
|
||||
from decnet.prober.jarm import JARM_EMPTY_HASH, jarm_hash
|
||||
from decnet.prober.tcpfp import tcp_fingerprint
|
||||
from decnet.prober.tlscert import fetch_leaf_cert
|
||||
from decnet.telemetry import traced as _traced
|
||||
|
||||
logger = get_logger("prober")
|
||||
@@ -305,6 +306,10 @@ def _jarm_phase(
|
||||
"jarm",
|
||||
{"attacker_ip": ip, "port": port, "jarm_hash": h},
|
||||
)
|
||||
# Cert capture: a non-empty JARM hash proves the port speaks
|
||||
# TLS, so a follow-up real handshake is worth attempting.
|
||||
# Failures are silent — the next probe target must not stall.
|
||||
_capture_tls_cert(ip, port, log_path, json_path, timeout, publish_fn)
|
||||
except Exception as exc:
|
||||
done.add(port)
|
||||
_write_event(
|
||||
@@ -319,6 +324,60 @@ def _jarm_phase(
|
||||
logger.warning("prober: JARM probe failed %s:%d: %s", ip, port, exc)
|
||||
|
||||
|
||||
@_traced("prober.tls_cert_capture")
|
||||
def _capture_tls_cert(
|
||||
ip: str,
|
||||
port: int,
|
||||
log_path: Path,
|
||||
json_path: Path,
|
||||
timeout: float,
|
||||
publish_fn: ProbePublishFn | None,
|
||||
) -> None:
|
||||
"""Fetch the leaf TLS cert from ``ip:port`` and emit a tls_certificate
|
||||
event. No-op when the handshake fails (silent — JARM already proved
|
||||
the port responds, but the real handshake can still fail for many
|
||||
reasons: cipher mismatch, SNI gating, mTLS requirement)."""
|
||||
try:
|
||||
cert = fetch_leaf_cert(ip, port, timeout=timeout)
|
||||
except Exception as exc:
|
||||
# fetch_leaf_cert is supposed to swallow errors; defense in depth.
|
||||
logger.warning("prober: TLS cert fetch crashed %s:%d: %s", ip, port, exc)
|
||||
return
|
||||
if cert is None:
|
||||
return
|
||||
|
||||
sans_csv = ",".join(cert["sans"])
|
||||
_write_event(
|
||||
log_path, json_path,
|
||||
"tls_certificate",
|
||||
target_ip=ip,
|
||||
target_port=str(port),
|
||||
subject_cn=cert["subject_cn"],
|
||||
issuer=cert["issuer"],
|
||||
self_signed=str(cert["self_signed"]).lower(),
|
||||
not_before=cert["not_before"],
|
||||
not_after=cert["not_after"],
|
||||
sans=sans_csv,
|
||||
cert_sha256=cert["cert_sha256"],
|
||||
msg=f"TLS cert {ip}:{port} CN={cert['subject_cn']} sha256={cert['cert_sha256'][:16]}...",
|
||||
)
|
||||
logger.info(
|
||||
"prober: TLS cert %s:%d CN=%s sha256=%s",
|
||||
ip, port, cert["subject_cn"], cert["cert_sha256"],
|
||||
)
|
||||
if publish_fn is not None:
|
||||
publish_fn(
|
||||
"tls_certificate",
|
||||
{
|
||||
"attacker_ip": ip,
|
||||
"port": port,
|
||||
"subject_cn": cert["subject_cn"],
|
||||
"cert_sha256": cert["cert_sha256"],
|
||||
"self_signed": cert["self_signed"],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
@_traced("prober.hassh_phase")
|
||||
def _hassh_phase(
|
||||
ip: str,
|
||||
|
||||
Reference in New Issue
Block a user