fn_registry/python/functions/cybersecurity/traceroute_host.md

name, kind, lang, domain, version, purity, signature, description, tags, params, output, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	params	output	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path
traceroute_host	function	py	cybersecurity	1.0.0	impure	def traceroute_host(host: str, max_hops: int = 30, timeout_s: int = 60) -> dict	Traza la ruta de red hacia un host ejecutando `traceroute -m <max_hops> -w 2 <host>` (Linux) por subprocess y parseando best-effort cada hop: numero de salto, hosts (nombre + IP) y rtt detectados por regex. Un hop sin respuesta ('* * *') tiene hosts vacio. Devuelve dict de estado sin lanzar; `raw` siempre presente con el stdout.	recon traceroute cybersecurity network route	name desc host Hostname o IP destino, ej. google.com o 1.1.1.1. Vacio devuelve status error. name desc max_hops Maximo numero de saltos a sondear (traceroute -m). Default 30. name desc timeout_s Timeout duro del subprocess en segundos (traceroute puede tardar si hay hops que no responden). Default 60.	dict de estado. En exito {status:'ok', host, hops:[{hop:int, hosts:[{name:str, ip:str, rtt_ms:[float,...]}]}], raw:str}; un hop sin respuesta ('* * *') tiene hosts=[]. En fallo {status:'error', error:str, host, raw:str}.				false	error_py_core		false			python/functions/cybersecurity/traceroute_host.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from cybersecurity import traceroute_host

res = traceroute_host("1.1.1.1", max_hops=20, timeout_s=40)
print(res["status"])                 # "ok"
print(len(res["hops"]))              # numero de saltos detectados
for hop in res["hops"][:5]:
    ips = [h["ip"] for h in hop["hosts"] if h["ip"]]
    print(hop["hop"], ips or "* * *")
print(res["raw"])                    # stdout crudo para el vault OSINT

Cuando usarla

Usala para mapear el camino de red (saltos intermedios, ASNs/proveedores por las IPs) hacia un objetivo durante el recon de infraestructura, despues de confirmar con ping_host que responde. Cada hop con su IP ayuda a inferir la topologia y el alojamiento del objetivo. Guarda raw como evidencia en la nota OSINT.

Gotchas

• Funcion impura: envia trafico de red (UDP/ICMP segun la implementacion de traceroute) a multiples saltos. No determinista (rutas cambian, latencia varia).
• Linux-only: usa la sintaxis traceroute -m N -w 2 del paquete traceroute. En otras plataformas (tracert en Windows, traceroute BSD) los flags y el formato difieren y el parseo fallaria.
• Hops filtrados son normales, no error: firewalls/routers que no decrementan TTL o no devuelven ICMP TTL-exceeded aparecen como "* * *" → hosts: []. Una traza incompleta o que no llega al destino es esperable, sigue status:"ok".
• Parseo best-effort por regex: captura numero de hop + IPs detectadas; los rtt de la linea se asocian a todos los hosts del hop (no se separa por sonda). Para fidelidad total mira raw.
• Requiere el binario traceroute en PATH. Si falta, devuelve {"status":"error",...} (no lanza). Puede necesitar privilegios segun el modo (raw sockets); si no los tiene, los hops pueden salir incompletos.
• Nunca lanza: errores en status. Si la traza tarda mas de timeout_s, es status:"error" con el stdout parcial en raw.
• Puede ser lento: con hops que no responden, traceroute espera el -w 2 por sonda; ajusta timeout_s en consecuencia.