fn_registry/python/functions/cybersecurity/ping_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
ping_host	function	py	cybersecurity	1.0.0	impure	def ping_host(host: str, count: int = 4, timeout_s: int = 30) -> dict	Sondeo de disponibilidad ICMP de un host ejecutando `ping -c <count> -w <timeout_s> <host>` (Linux) por subprocess y parseando el resumen: paquetes enviados/recibidos, % de perdida y rtt min/avg/max. Devuelve dict de estado sin lanzar; host inalcanzable o ICMP filtrado es status ok con loss_pct=100 y rtt None. `raw` siempre presente con el stdout.	recon ping cybersecurity icmp network	name desc host Hostname o IP a sondear, ej. 1.1.1.1 o google.com. Vacio devuelve status error. name desc count Numero de echo requests ICMP a enviar (ping -c). Default 4. name desc timeout_s Deadline total del ping en segundos (ping -w); tambien fija el timeout duro del subprocess (con +5s de margen). Default 30.	dict de estado. En exito {status:'ok', host, packets_sent:int|None, packets_recv:int|None, loss_pct:float, rtt_avg_ms:float|None, rtt_min_ms:float|None, rtt_max_ms:float|None, raw:str}; un host inalcanzable da loss_pct=100 y rtts None pero sigue status ok. En fallo {status:'error', error:str, host, raw:str}.				false	error_py_core		false			python/functions/cybersecurity/ping_host.py

Ejemplo

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

res = ping_host("1.1.1.1", count=4, timeout_s=10)
print(res["status"])         # "ok"
print(res["loss_pct"])       # 0.0
print(res["rtt_avg_ms"])     # 12.3
print(res["raw"])            # stdout crudo de ping para el vault

Cuando usarla

Usala para comprobar rapidamente si un host responde a ICMP y medir su latencia antes de un escaneo mas pesado (traceroute, port scan). Util para verificar conectividad y caracterizar la red de un objetivo en una fase de recon. Guarda raw como evidencia en la nota OSINT.

Gotchas

• Funcion impura: envia trafico ICMP a la red. No determinista (latencia varia).
• Linux-only: usa la sintaxis ping -c N -w S de iputils. En BSD/macOS los flags difieren (-t en vez de -w) y el parseo podria fallar.
• ICMP suele estar filtrado por firewalls: un host que SI existe puede no responder a ping. Eso es status:"ok" con loss_pct=100 y rtt None, NO un error. No concluyas "host caido" solo por perdida total.
• Requiere el binario ping en PATH (paquete iputils-ping). Si falta, devuelve {"status":"error",...} (no lanza). En algunos sistemas ping necesita capacidad cap_net_raw o setuid; si no la tiene puede fallar.
• Nunca lanza: errores en status. El timeout duro del subprocess es timeout_s + 5s; si se alcanza, es status:"error".
• packets_sent/packets_recv pueden ser None si la version de ping emite un resumen con formato inesperado; en ese caso revisa raw.