anti/DECNET
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(prober): generalise ActiveProbe registry to absorb Ipv6LeakProbe

Browse Source 
ActiveProbe.run/syslog_fields/publish_payload now accept port=None so
non-port-iterating probes can live in the registry. Ipv6LeakProbe replaces
the hand-rolled _ipv6_leak_phase special case in worker.py; it runs last
via priority=999. _probe_cycle no longer has an ad-hoc phase call.

Fixes three stale test files (test_prober_bus, test_prober_rotation,
test_prober_worker) that were broken since the 916b21b6 registry refactor.
This commit is contained in:
anti
2026-05-21 14:27:48 -04:00
parent b80e621904
commit bd4700770b
12 changed files with 409 additions and 420 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
decnet/prober/base.py
View File

@@ -48,7 +48,7 @@ class ActiveProbe(metaclass=ActiveProbeMeta):
"""
probe_name: str
default_ports: list[int]
default_ports: list[int | None]
event_type: str
rotation_type: ProbeType | None = None
rotation_hash_key: str | None = None
@@ -59,26 +59,26 @@ class ActiveProbe(metaclass=ActiveProbeMeta):
raw = os.environ.get(env_key, "").strip()
if raw:
try:
self._ports: list[int] = [int(p.strip()) for p in raw.split(",") if p.strip()]
self._ports: list[int | None] = [int(p.strip()) for p in raw.split(",") if p.strip()]
except ValueError:
self._ports = list(self.default_ports)
else:
self._ports = list(self.default_ports)
@property
def ports(self) -> list[int]:
def ports(self) -> list[int | None]:
return self._ports
@abstractmethod
def run(self, ip: str, port: int, timeout: float) -> dict[str, Any] | None:
"""Execute the probe against ip:port.
def run(self, ip: str, port: int | None, timeout: float) -> dict[str, Any] | None:
"""Execute the probe against ip:port (port is None for port-free probes).
Return a result dict on success, or None to suppress emission (e.g.
empty JARM hash means the port doesn't speak TLS).
"""
@abstractmethod
def syslog_fields(self, ip: str, port: int, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
def syslog_fields(self, ip: str, port: int | None, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
"""Return (sd_fields, human_msg) for _write_event.
target_ip and target_port are injected by _run_probe; do not include
@@ -86,5 +86,5 @@ class ActiveProbe(metaclass=ActiveProbeMeta):
"""
@abstractmethod
def publish_payload(self, ip: str, port: int, result: dict[str, Any]) -> dict[str, Any]:
def publish_payload(self, ip: str, port: int | None, result: dict[str, Any]) -> dict[str, Any]:
"""Return the bus payload dict for attacker.fingerprinted events."""

1
decnet/prober/probes/__init__.py
View File

@@ -1,4 +1,5 @@
# Import all probe modules to trigger ActiveProbeMeta registration.
from decnet.prober.probes.hassh import HasshProbe as HasshProbe
from decnet.prober.probes.ipv6_leak_probe import Ipv6LeakProbe as Ipv6LeakProbe
from decnet.prober.probes.jarm import JarmProbe as JarmProbe
from decnet.prober.probes.tcpfp import TcpfpProbe as TcpfpProbe

12
decnet/prober/probes/hassh.py
View File

@@ -6,22 +6,24 @@ from decnet.prober.base import ActiveProbe
from decnet.prober.hassh import hassh_server
from decnet.telemetry import traced as _traced
DEFAULT_PORTS: list[int] = [22, 2222, 22222, 2022]
DEFAULT_PORTS: list[int | None] = [22, 2222, 22222, 2022]
class HasshProbe(ActiveProbe):
probe_name = "hassh"
default_ports = DEFAULT_PORTS
default_ports: list[int | None] = DEFAULT_PORTS
event_type = "hassh_fingerprint"
rotation_type = "hassh"
rotation_hash_key = "hassh_server"
priority = 100
@_traced("prober.hassh_probe")
def run(self, ip: str, port: int, timeout: float) -> dict[str, Any] | None:
def run(self, ip: str, port: int | None, timeout: float) -> dict[str, Any] | None:
if port is None:
return None
return hassh_server(ip, port, timeout=timeout)
def syslog_fields(self, ip: str, port: int, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
def syslog_fields(self, ip: str, port: int | None, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
fields = {
"hassh_server_hash": result["hassh_server"],
"ssh_banner": result["banner"],
@@ -32,7 +34,7 @@ class HasshProbe(ActiveProbe):
}
return fields, f"HASSH {ip}:{port} = {result['hassh_server']}"
def publish_payload(self, ip: str, port: int, result: dict[str, Any]) -> dict[str, Any]:
def publish_payload(self, ip: str, port: int | None, result: dict[str, Any]) -> dict[str, Any]:
return {
"attacker_ip": ip,
"port": port,

62
decnet/prober/probes/ipv6_leak_probe.py Normal file
View File

@@ -0,0 +1,62 @@
from __future__ import annotations
from typing import Any
from decnet.logging import get_logger
from decnet.prober.base import ActiveProbe
_log = get_logger("prober.ipv6_leak_probe")
class Ipv6LeakProbe(ActiveProbe):
"""Port-free active probe that solicits a fe80:: response from the attacker.
Sends ICMPv6 Echo Request to ff02::1 on the attacker's reachable iface
to reveal the attacker's IPv6 IID / MAC-derived address.
Only fires when the attacker is directly reachable on L2 (no gateway).
Runs last (priority=999) so all TCP-level probes complete first.
"""
probe_name = "ipv6_leak"
default_ports: list[int | None] = [None]
event_type = "ipv6_link_local_leak"
priority = 999
def run(self, ip: str, port: int | None, timeout: float) -> dict[str, Any] | None:
from decnet.prober.ipv6_leak import _route_info, solicit_ipv6_leak
on_link, iface = _route_info(ip)
if not on_link:
_log.debug("ipv6_leak_probe: %s is not on-link — skip", ip)
return None
if iface is None:
_log.debug("ipv6_leak_probe: cannot determine iface for %s — skip", ip)
return None
return solicit_ipv6_leak(ip, iface, timeout=timeout)
def syslog_fields(
self, ip: str, port: int | None, result: dict[str, Any]
) -> tuple[dict[str, Any], str]:
addr = result.get("addr", "")
iid_kind = result.get("iid_kind", "")
fields = {
"ipv6_addr": addr,
"iid_kind": iid_kind,
"mac_oui": result.get("mac_oui", ""),
"on_iface": result.get("on_iface", ""),
"vector": result.get("vector", ""),
}
return fields, f"IPv6 leak {ip} → {addr} ({iid_kind})"
def publish_payload(
self, ip: str, port: int | None, result: dict[str, Any]
) -> dict[str, Any]:
return {
"attacker_ip": ip,
"addr": result.get("addr", ""),
"iid_kind": result.get("iid_kind", ""),
"mac_oui": result.get("mac_oui", ""),
"vector": result.get("vector", ""),
"on_iface": result.get("on_iface", ""),
"observed_at": result.get("observed_at", ""),
}

12
decnet/prober/probes/jarm.py
View File

@@ -6,27 +6,29 @@ from decnet.prober.base import ActiveProbe
from decnet.prober.jarm import JARM_EMPTY_HASH, jarm_hash
from decnet.telemetry import traced as _traced
DEFAULT_PORTS: list[int] = [443, 8443, 8080, 4443, 50050, 2222, 993, 995, 8888, 9001]
DEFAULT_PORTS: list[int | None] = [443, 8443, 8080, 4443, 50050, 2222, 993, 995, 8888, 9001]
class JarmProbe(ActiveProbe):
probe_name = "jarm"
default_ports = DEFAULT_PORTS
default_ports: list[int | None] = DEFAULT_PORTS
event_type = "jarm_fingerprint"
rotation_type = "jarm"
rotation_hash_key = "jarm_hash"
priority = 100
@_traced("prober.jarm_probe")
def run(self, ip: str, port: int, timeout: float) -> dict[str, Any] | None:
def run(self, ip: str, port: int | None, timeout: float) -> dict[str, Any] | None:
if port is None:
return None
h = jarm_hash(ip, port, timeout=timeout)
if h == JARM_EMPTY_HASH:
return None
return {"jarm_hash": h}
def syslog_fields(self, ip: str, port: int, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
def syslog_fields(self, ip: str, port: int | None, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
h = result["jarm_hash"]
return {"jarm_hash": h}, f"JARM {ip}:{port} = {h}"
def publish_payload(self, ip: str, port: int, result: dict[str, Any]) -> dict[str, Any]:
def publish_payload(self, ip: str, port: int | None, result: dict[str, Any]) -> dict[str, Any]:
return {"attacker_ip": ip, "port": port, "jarm_hash": result["jarm_hash"]}

12
decnet/prober/probes/tcpfp.py
View File

@@ -6,22 +6,24 @@ from decnet.prober.base import ActiveProbe
from decnet.prober.tcpfp import tcp_fingerprint
from decnet.telemetry import traced as _traced
DEFAULT_PORTS: list[int] = [22, 80, 443, 8080, 8443, 445, 3389]
DEFAULT_PORTS: list[int | None] = [22, 80, 443, 8080, 8443, 445, 3389]
class TcpfpProbe(ActiveProbe):
probe_name = "tcpfp"
default_ports = DEFAULT_PORTS
default_ports: list[int | None] = DEFAULT_PORTS
event_type = "tcpfp_fingerprint"
rotation_type = "tcpfp"
rotation_hash_key = "tcpfp_hash"
priority = 100
@_traced("prober.tcpfp_probe")
def run(self, ip: str, port: int, timeout: float) -> dict[str, Any] | None:
def run(self, ip: str, port: int | None, timeout: float) -> dict[str, Any] | None:
if port is None:
return None
return tcp_fingerprint(ip, port, timeout=timeout)
def syslog_fields(self, ip: str, port: int, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
def syslog_fields(self, ip: str, port: int | None, result: dict[str, Any]) -> tuple[dict[str, Any], str]:
fields = {
"tcpfp_hash": result["tcpfp_hash"],
"tcpfp_raw": result["tcpfp_raw"],
@@ -40,7 +42,7 @@ class TcpfpProbe(ActiveProbe):
}
return fields, f"TCPFP {ip}:{port} = {result['tcpfp_hash']}"
def publish_payload(self, ip: str, port: int, result: dict[str, Any]) -> dict[str, Any]:
def publish_payload(self, ip: str, port: int | None, result: dict[str, Any]) -> dict[str, Any]:
return {
"attacker_ip": ip,
"port": port,

97
decnet/prober/worker.py
View File

@@ -253,18 +253,19 @@ RotationRecorderFn = Callable[[str, int, "ProbeType", str], None]
def _run_probe(
probe: ActiveProbe,
ip: str,
ip_probed: dict[str, set[int]],
ip_probed: dict[str, set[int | None]],
log_path: Path,
json_path: Path,
timeout: float,
publish_fn: ProbePublishFn | None,
record_rotation: RotationRecorderFn | None,
) -> None:
"""Generic driver for any port-iterating ActiveProbe."""
"""Generic driver for any ActiveProbe (port-iterating or port-free)."""
done = ip_probed.setdefault(probe.probe_name, set())
for port in probe.ports:
if port in done:
continue
port_label = str(port) if port is not None else "-"
try:
result = probe.run(ip, port, timeout)
done.add(port)
@@ -275,16 +276,16 @@ def _run_probe(
log_path, json_path,
probe.event_type,
target_ip=ip,
target_port=str(port),
target_port=port_label,
msg=msg,
**fields,
)
logger.info("prober: %s %s:%d ok", probe.probe_name, ip, port)
if record_rotation is not None and probe.rotation_type and probe.rotation_hash_key:
logger.info("prober: %s %s:%s ok", probe.probe_name, ip, port_label)
if record_rotation is not None and probe.rotation_type and probe.rotation_hash_key and port is not None:
record_rotation(ip, port, probe.rotation_type, result[probe.rotation_hash_key])
if publish_fn is not None:
publish_fn(probe.probe_name, probe.publish_payload(ip, port, result))
if probe.probe_name == "jarm":
if probe.probe_name == "jarm" and port is not None:
# A non-empty JARM hash proves TLS; attempt a real cert capture.
_capture_tls_cert(ip, port, log_path, json_path, timeout, publish_fn)
except Exception as exc:
@@ -294,17 +295,17 @@ def _run_probe(
"prober_error",
severity=_SEVERITY_WARNING,
target_ip=ip,
target_port=str(port),
target_port=port_label,
error=str(exc),
msg=f"{probe.probe_name} probe failed for {ip}:{port}: {exc}",
msg=f"{probe.probe_name} probe failed for {ip}:{port_label}: {exc}",
)
logger.warning("prober: %s probe failed %s:%d: %s", probe.probe_name, ip, port, exc)
logger.warning("prober: %s probe failed %s:%s: %s", probe.probe_name, ip, port_label, exc)
@_traced("prober.probe_cycle")
def _probe_cycle(
targets: set[str],
probed: dict[str, dict[str, set[int]]],
probed: dict[str, dict[str, set[int | None]]],
log_path: Path,
json_path: Path,
timeout: float = 5.0,
@@ -314,17 +315,14 @@ def _probe_cycle(
"""Probe all known attacker IPs via every registered ActiveProbe.
Probes run in (priority, probe_name) order per ActiveProbeMeta.all().
IPv6 leak runs last — it is not port-iterating and stays a special case.
Port-free probes (e.g. Ipv6LeakProbe, priority=999) run last by convention.
"""
for ip in sorted(targets):
ip_probed = probed.setdefault(ip, {})
for probe_cls in ActiveProbeMeta.all():
_run_probe(probe_cls(), ip, ip_probed, log_path, json_path,
timeout, publish_fn, record_rotation)
_ipv6_leak_phase(ip, ip_probed, log_path, json_path, timeout, publish_fn)
@_traced("prober.tls_cert_capture")
def _capture_tls_cert(
@@ -380,73 +378,6 @@ def _capture_tls_cert(
)
@_traced("prober.ipv6_leak_phase")
def _ipv6_leak_phase(
ip: str,
ip_probed: dict[str, set[int]],
log_path: Path,
json_path: Path,
timeout: float,
publish_fn: ProbePublishFn | None = None,
) -> None:
"""Attempt active ICMPv6 solicitation to elicit a fe80:: response.
Skipped when:
- already attempted for this attacker in this cycle
- attacker is not on a directly connected (link-local reachable) L2
- scapy unavailable or the local iface has no fe80:: address
"""
done = ip_probed.setdefault("ipv6_leak", set())
# Use port 0 as a sentinel (no port concept for ICMPv6 probes).
if 0 in done:
return
done.add(0)
from decnet.prober.ipv6_leak import _route_info, solicit_ipv6_leak
on_link, iface = _route_info(ip)
if not on_link:
logger.debug("prober: ipv6_leak: %s is not on-link — skip active probe", ip)
return
if iface is None:
logger.debug("prober: ipv6_leak: cannot determine iface for %s", ip)
return
try:
evidence = solicit_ipv6_leak(ip, iface, timeout=timeout)
except Exception as exc:
logger.warning("prober: ipv6_leak active probe failed %s: %s", ip, exc)
return
if evidence is None:
return
_write_event(
log_path, json_path,
"ipv6_link_local_leak",
target_ip=ip,
ipv6_addr=evidence.get("addr", ""),
iid_kind=evidence.get("iid_kind", ""),
mac_oui=evidence.get("mac_oui", ""),
on_iface=evidence.get("on_iface", ""),
vector=evidence.get("vector", ""),
msg=f"IPv6 leak {ip} → {evidence.get('addr', '')} ({evidence.get('iid_kind', '')})",
)
logger.info(
"prober: ipv6_leak %s → %s kind=%s oui=%s",
ip, evidence.get("addr"), evidence.get("iid_kind"), evidence.get("mac_oui"),
)
if publish_fn is not None:
publish_fn("ipv6_leak", {
"attacker_ip": ip,
"addr": evidence.get("addr", ""),
"iid_kind": evidence.get("iid_kind", ""),
"mac_oui": evidence.get("mac_oui", ""),
"vector": evidence.get("vector", ""),
"on_iface": evidence.get("on_iface", ""),
"observed_at": evidence.get("observed_at", ""),
})
# ─── Main worker ─────────────────────────────────────────────────────────────
@@ -461,7 +392,7 @@ async def prober_worker(
Discovers attacker IPs automatically by tailing the JSON log file,
then fingerprints each IP via every registered ActiveProbe (JARM,
HASSH, TCP/IP stack) plus the IPv6 leak special case.
HASSH, TCP/IP stack, IPv6 leak) in priority order.
Per-probe port lists are taken from each probe's ``default_ports``
attribute. Override at runtime via DECNET_PROBE_PORTS_<NAME_UPPER>
@@ -495,7 +426,7 @@ async def prober_worker(
)
known_attackers: set[str] = set()
probed: dict[str, dict[str, set[int]]] = {} # IP -> {type -> ports}
probed: dict[str, dict[str, set[int | None]]] = {} # IP -> {probe_name -> ports/None}
log_position: int = 0
loop = asyncio.get_running_loop()