---
name: ping_host
kind: function
lang: py
domain: cybersecurity
version: "1.0.0"
purity: impure
signature: "def ping_host(host: str, count: int = 4, timeout_s: int = 30) -> dict"
description: "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."
tags: [recon, ping, cybersecurity, icmp, network]
params:
  - name: host
    desc: "Hostname o IP a sondear, ej. 1.1.1.1 o google.com. Vacio devuelve status error."
  - name: count
    desc: "Numero de echo requests ICMP a enviar (ping -c). Default 4."
  - name: timeout_s
    desc: "Deadline total del ping en segundos (ping -w); tambien fija el timeout duro del subprocess (con +5s de margen). Default 30."
output: "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}."
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_py_core"
imports: []
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/cybersecurity/ping_host.py"
---

## Ejemplo

```python
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`.