Autodetección

Cómo funciona

Tanto el agente como el recolector envían un informe a ipmanager con POST /api/v1/agent/report por HTTPS, con una clave API en la cabecera Authorization. ipmanager hace lo siguiente con cada dirección del informe:

• Dirección nueva: se crea con estado «en uso» y el origen se marca como agente o escaneo.
• Dirección conocida: se actualiza «visto por última vez». Si cambia el hostname o la MAC, se actualiza y se anota en el registro de auditoría.
• Dirección que estaba libre o desconectada: vuelve a «en uso».
• Sin cambios: solo se actualiza «visto por última vez», sin nueva entrada de auditoría.

Si la organización ha alcanzado su límite de direcciones, no se crean direcciones nuevas. Se cuentan como limited en la respuesta, mientras que las conocidas se siguen actualizando.

1. Crea una clave API

Ve a Autodetección y API en ipmanager y crea una clave nueva con el permiso agent. Una clave de agente solo puede enviar informes: no puede leer ni borrar datos. La clave se muestra una sola vez, así que guárdala bien. Conviene crear una clave por sede o recolector para poder revocar una sin afectar a las demás.

2a. Agente en Linux y macOS

curl -fsSo /usr/local/bin/ipm-agent.sh https://ipmanager.no/api/v1/agent/scripts/ipm-agent.sh
chmod 755 /usr/local/bin/ipm-agent.sh

# Prueba
IPM_TOKEN=ipm_xxxxxxxx sh /usr/local/bin/ipm-agent.sh

Guarda la clave en un archivo que solo pueda leer root, no en el crontab:

mkdir -p /etc/ipmanager
echo 'IPM_TOKEN=ipm_xxxxxxxx' > /etc/ipmanager/agent.env
chmod 600 /etc/ipmanager/agent.env

# /etc/cron.d/ipmanager – informe cada 15 minutos
*/15 * * * * root . /etc/ipmanager/agent.env && IPM_TOKEN=$IPM_TOKEN sh /usr/local/bin/ipm-agent.sh >/dev/null 2>&1

# /etc/systemd/system/ipm-agent.service
[Unit]
Description=ipmanager agent
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
EnvironmentFile=/etc/ipmanager/agent.env
ExecStart=/bin/sh /usr/local/bin/ipm-agent.sh

# /etc/systemd/system/ipm-agent.timer
[Unit]
Description=Run ipmanager agent every 15 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min
RandomizedDelaySec=60

[Install]
WantedBy=timers.target

systemctl daemon-reload
systemctl enable --now ipm-agent.timer

2b. Agente en Windows

New-Item -ItemType Directory -Force C:\ProgramData\ipmanager | Out-Null
Invoke-WebRequest https://ipmanager.no/api/v1/agent/scripts/ipm-agent.ps1 -OutFile C:\ProgramData\ipmanager\ipm-agent.ps1

# Prueba
$env:IPM_TOKEN = 'ipm_xxxxxxxx'
powershell -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\ipmanager\ipm-agent.ps1

[Environment]::SetEnvironmentVariable('IPM_TOKEN', 'ipm_xxxxxxxx', 'Machine')

schtasks /Create /TN "ipmanager agent" /RU SYSTEM /SC MINUTE /MO 15 /F `
  /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\ProgramData\ipmanager\ipm-agent.ps1"

3. Recolector dentro de tu propia red

El recolector es un único script de Python 3 sin dependencias. Se ejecuta en un equipo de la red (un servidor, una máquina virtual o un pequeño equipo Linux) y hace de intermediario: ve la red desde dentro e informa hacia fuera a ipmanager.

curl -fsSO https://ipmanager.no/api/v1/agent/scripts/ipm-collector.py
python3 ipm-collector.py --help

# Barrido de dos redes incluyendo la tabla ARP
python3 ipm-collector.py --token ipm_xxxxxxxx --arp 10.20.0.0/24 10.20.3.0/24

El recolector hace ping a las direcciones de las redes indicadas, lee la tabla ARP del equipo para obtener las MAC, resuelve el DNS inverso para los hostnames y puede leer concesiones de dnsmasq e ISC DHCP. Consulta --help para ver todas las opciones.

# /etc/cron.d/ipmanager-collector – cada hora
0 * * * * root . /etc/ipmanager/agent.env && python3 /opt/ipmanager/ipm-collector.py --token "$IPM_TOKEN" --arp 10.20.0.0/16 >/dev/null 2>&1

4. Comprobación DNS de nombres internos

Las direcciones IP públicas se comprueban automáticamente desde ipmanager.no contra el DNS público una vez al día. Los nombres internos, como .local o el DNS de Active Directory, solo se pueden consultar desde dentro. Por eso el recolector puede comprobarlos con --dns-check, usando el servidor DNS de tu propia red.

El recolector obtiene las direcciones registradas con hostname de las redes indicadas, consulta el PTR de cada IP y el registro A/AAAA de cada nombre y comunica el resultado. ipmanager asigna el estado OK, desajuste o falta (PTR o A/AAAA), y los desajustes aparecen también en Conflictos. Con --no-scan el recolector omite el barrido ping y solo comprueba el DNS.

IPM_TOKEN=ipm_xxxxxxxx python3 ipm-collector.py --dns-check --no-scan 10.20.0.0/16

# /etc/cron.d/ipmanager-dns – cada noche a las 03:15
15 3 * * * root . /etc/ipmanager/agent.env && IPM_TOKEN="$IPM_TOKEN" python3 /opt/ipmanager/ipm-collector.py --dns-check --no-scan 10.20.0.0/16 >/dev/null 2>&1

Si usas hostnames cortos, indica un sufijo DNS en ipmanager para que archivos01 se compruebe como archivos01.empresa.local. Las direcciones sin hostname reciben una sugerencia del PTR que se aplica con un clic.

Conflictos a partir de los informes

Los informes de agentes y recolector también sirven para detectar conflictos: IP duplicadas (dos MAC en la misma IP en pocos minutos), otra MAC en una IP registrada (la MAC registrada no se sobrescribe), una MAC conocida en otra IP, equipos en direcciones registradas como libres, reservadas u obsoletas, IP fuera de las subredes registradas, direcciones estáticas dentro de rangos DHCP y hostnames cambiados. Los conflictos se resuelven solos cuando desaparece la condición y los administradores reciben un correo con los conflictos críticos y avisos nuevos.

Cortafuegos y red

• El agente y el recolector solo necesitan TCP 443 saliente hacia ipmanager.no. No hay que abrir nada de entrada.
• El recolector debe poder enviar ICMP echo (ping) a las redes que barre. Los equipos cuyo cortafuegos bloquee el ping no aparecerán por ping, pero pueden aparecer por ARP o DHCP.
• Si el tráfico saliente pasa por un proxy, los scripts pueden usar las variables de proxy estándar (HTTPS_PROXY).

Seguridad

• Usa claves con el permiso agent. Solo pueden informar, no leer ni borrar.
• Guarda la clave en un archivo que solo puedan leer root o SYSTEM, no en scripts versionados.
• La página de claves API muestra cuándo se usó cada clave por última vez y desde qué IP. Revoca las que no se usen.
• Los scripts son texto plano. Revísalos antes de ejecutarlos.

Resolución de problemas

Consulta la documentación de la API para ver el formato exacto del informe.